Developer
Log in

Extensions

Extensions

Extensions are code that lives inside Studio. Today that means source plugins, things you add to a scene, and they look like Velum made them because Studio draws their settings with its own controls.

Where extensions stand

Studio's plugin host ships, on plugin ABI 1.3. Source plugins run today: they draw pictures and make sound, out of process, with their settings in the Inspector. Other kinds (docks, chat, layer creation, outputs) are planned, and they're marked that way below. The plugin SDK is MIT licensed.

Integrations or extensions?

Integrations Extensions
What Other apps controlling Studio from outside: Companion, Touch Portal, Stream Deck, bots, scripts Code that lives inside Studio. Today: sources. Planned: docks, filters, transitions, outputs, automation steps, detectors
How The control API and the SDKs The plugin ABI and .velumplugin packages
Design rules None. They're their own apps. The design guidelines. They look like Velum made them.

If your idea works from outside Studio, build an integration: it needs nothing from Studio but the API.

What a plugin can do today

A plugin is one native library (a .dll, .dylib or .so) that exports a single C function, velum_plugin_entry. It hands Studio one or more source types, and people add them to scenes from Add source like any of Studio's own.

  • Run out of process. Every plugin runs in its own velum-plugin-host process, never inside Studio. If it crashes or hangs, only its own layers show a placeholder frame while the host restarts. The stream never waits for a plugin. See Crashes and hangs.
  • Draw a picture. Write the frame from memory (8-bit RGBA, premultiplied alpha), or draw it on the GPU straight into the image Studio composes: Vulkan on Linux, Direct3D 12 (or 11) on Windows, Metal on macOS, or wgpu through the Rust SDK, which does the sharing for you. No copies, and Studio never waits on your GPU work.
  • Make sound, on its own mixer channel. A source type marked as audio fills 48 kHz float blocks in real time, and gets its own channel in Studio's mixer, like any other source with sound.
  • Listen. A setting can pick a microphone or another source's sound, and Studio feeds that audio to the plugin as the mixer has it (after filters, before the fader), every 10 ms.
  • Declare settings; Studio draws them. A plugin lists its properties (toggles, numbers with a unit, choices, colors, text, files, fonts, lists, buttons, a picker for another source or scene, a device picker, and secrets) and the Inspector shows them as native cards with Studio's own widgets, headings and tooltips. Nothing of the plugin's own UI is drawn. Since 1.2 a plugin can also open its own windows and live previews, drawn the same way, and since 1.3 it can add read-only status lines, preset choices, and a "Copy look from…" for its look settings.
  • Be automated. Settings the plugin marks as automatable are offered to hotkeys, automations, Stream Deck, Touch Portal and the control API (source.set, source.trigger and the source_settings topic). Everything else stays in the Inspector.
  • Keep secrets safe. A secret setting (an API token, say) is stored in the operating system's keychain. The scene collection holds only a handle, and the plugin reads the value when it needs it.
  • Change its own settings as one undoable step (1.3), named in Edit › Undo and saved with the collection.
  • Ship as one file. A .velumplugin carries the manifest and a binary per platform. Open it in Studio to install it. Studio checks every file and the signature, installs it per user, and keeps the previous version for rollback.
  • Be listed in the gallery. Sign your package, then submit it through a Velum Connect developer account. After the automated checks and a person's review it's countersigned and listed with the Made for Velum mark. See Review and listing.

Velum Avatars is built this way: a first-party source plugin whose expressions, camera, light and outfit are automatable settings.

Planned

These are planned and not in Studio yet. Don't build against them yet: their interfaces will arrive as new ABI minors.

Planned What it adds
Native panels (docks) A web page or a QML root inside a Studio dock, with Studio's header, pop-out, tabbing and layout restore, a themed UI kit, and a stable dock_id
Chat ingest Reading the chat Studio already pulls in, and sending to it (the chat:read and chat:send permissions)
Layer creation A plugin adding and arranging layers and sources in scenes (scenes:write)
Output plugins New destinations and encoders (the output and encoder kinds)
Filters, transitions, automation steps, detectors Effects on a source, what plays between scenes, steps for Studio's automations, and Screen Detect backends
Permission prompts The manifest's permissions shown in plain words at install, and revocable later

Until then, Studio won't install a plugin whose kinds don't include source: it says it runs source plugins so far.

The right way is the easy way

Guidelines that rely on policing fail, so most of them are enforced by the toolkit itself:

  • Studio draws the settings. A plugin declares what it has, and the Inspector shows it with Studio's own controls, in both themes. There's no plugin UI to get wrong.
  • Studio owns the frame. Planned docks get Studio's own header, pop-out, close, tabbing, floating and layout restore. Following the rules will be less work than breaking them.
  • Studio ships the UI kit for planned docks, already themed: buttons, fields, sliders, lists, tabs, pickers, meters, empty states and more.

Review decides only what gets listed in the gallery, never what's allowed to run.

Kinds of extension

Kind What it is Status
source Something on the canvas or in the mixer: a picture, a sound, or both Available (ABI 1.0 to 1.3)
dock A panel: a web page or a QML root, with a stable dock_id so layouts save and restore it Planned
filter A video or audio effect on a source Planned
transition What plays between two scenes Planned
output, encoder Where a stream goes, and how it's encoded Planned
automation A trigger, condition or action for Studio's automations Planned
detector A Screen Detect backend: looks at a region of the screen and reports what it sees Planned

Native plugins use a plain C ABI with one exported entry point. It's versioned so a newer Studio keeps loading older plugins: minors only ever add to the end of a table. The full reference is Plugin ABI.

Permissions

A plugin declares what it needs in its manifest: scenes:read and scenes:write, chat:read and chat:send, stream:control, audio:control, network:<hosts>, camera, microphone, screen, and filesystem:<scope>. The gallery checks that a plugin asks only for permissions Studio knows. Showing them in plain words at install ("This extension can read your chat and change scenes"), and revoking them later, is planned. Declare what you use now, so your package is ready.

Trust

Studio reads a plugin's trust from its signature when you open the file, and shows it before you install.

Level Who Where it runs
First-party Signed by the publisher, Legendre Media Inc. Its own host process
Verified A developer key registered with the publisher, the package countersigned by the publisher (confirms the developer's signature, never replaces it) Its own host process
Community Unsigned or self-signed Its own host process
Blocked On the revocation list Never: Studio refuses to run it

Sideloading stays open. Community plugins are allowed and never blocked for style; Studio says so plainly when you open one: "Not reviewed: runs on its own, with only what it asks for". Listed plugins, the ones in the gallery, carry the Made for Velum mark.

The SDK and its license

The plugin SDK is MIT licensed: the C header velum_plugin.h, the Rust crate velum-plugin-sdk (with an optional wgpu feature that does the GPU sharing for you), and two sample plugins (a C gradient and tone, and a wgpu cube that pulses with a microphone). So are the client SDKs for the control API. Build open or closed, free or paid plugins on it. Velum Studio itself is proprietary.

In this section

  • Plugin ABI: the entry point, every table and function, the lifecycle, threads and deadlines.
  • Design guidelines: the frame, tokens, the UI kit, words, states, accessibility and performance.
  • Packaging and signing: .velumplugin, its manifest, and the signature.
  • Review and listing: what review checks, and how a listed extension differs from a sideloaded one.

to open · ↑ ↓ to move · Esc to close