Skip to main content

Stream Deck Plugin

The FXCanvas Stream Deck plugin puts your show on physical keys. Pin the sources, palettes, and effects that you perform with to fixed positions. One press makes the item live. Each key shows a preview thumbnail, and a red border marks the item that drives the output. A folder view is also available, for the items that you did not pin in advance.

The plugin communicates with FXCanvas through the REST API only. It installs nothing into FXCanvas. The show machine needs only its REST server enabled.

Requires a license

The plugin drives the REST API. The REST API server runs only with an activated license. In the free tier FXCanvas disables the Enable REST API Server checkbox, and every plugin key stays on Offline. See What requires a license.

Requirements:

  • Stream Deck software 6.5 or later (Windows 10+ or macOS 12+)
  • FXCanvas with an active REST API server, reachable from the Stream Deck machine

Installation​

The plugin ships as one .streamDeckPlugin package. Build it from the repository. Then give it to the Stream Deck software.

  1. Install Node.js 20 or later. Then open a terminal in integrations/streamdeck inside the FXCanvas repository.

  2. Run npm install one time to get the workspace dependencies.

  3. Run npm run pack. The script builds both packages, makes sure that the layering rules hold, and packs the plugin. After a success the script exits 0 and leaves one package at integrations/streamdeck/dist/com.fxcanvas.streamdeck.streamDeckPlugin. After a failure the script names the step that failed and leaves no package.

  4. If the Stream Deck software runs, quit it. It then loads the plugin correctly at the next start.

  5. Double-click the .streamDeckPlugin file. The Stream Deck software asks for confirmation and installs the plugin.

    A Stream Deck must be connected

    The Stream Deck software starts a plugin only after you put one of its actions on a device. With no Stream Deck attached, FXCanvas still appears in the actions list. No key renders, and the plugin does not run.

  6. Start the Stream Deck software. Make sure that FXCanvas appears in the actions list on the right, with the Pin, Browse, and Navigate actions.

  7. Drag the actions onto the keys. See Laying out your deck below.

To uninstall the plugin, right-click FXCanvas in the actions list. Then select the uninstall command. This is the same procedure as for any other plugin.

Laying out your deck​

The plugin ships three actions. Select between them by what you know in advance about the key.

ActionUse it for
PinOne key, one item. The sources, palettes, and effects that you perform with.
BrowseThe folder view, to find an item that you did not pin.
NavigateOne level up, and the pages inside a folder. Useful only next to Browse keys.

Start with Pin​

A show runs on this surface. Drag Pin onto a key. Select the key to open the property inspector. Then select an entry from the Item list. The list holds every source, every palette, and every effect that FXCanvas can load. The key keeps that item, in that position, after every other change.

The list is long on a real installation, so make it shorter before you scroll. Type in the filter box to match on name. Then use the dropdown beside it to show one group only:

FilterShows
All sourcesEverything below, in one list
Shader sourcesThe built-in shader source types
ISF sourcesSource types from standalone .isf / .fs files
Source presetsYour saved source presets
Live inputsCameras, capture cards, NDI senders
File mediaEverything the media library indexed
PalettesYour palettes, with their colors as swatches
EffectsEvery effect type FXCanvas can load

A useful 5×3 layout gives one row to each group:

row 1   the five sources you switch between
row 2   the five effects you drop in and out
row 3   four palettes, plus a Navigate "up" key

A pinned key shows the preview thumbnail of the item, its name, and a red border when it is live. Only one source and only one palette can be live, so each of these two groups shows one border at most. Effects are different. A row of effect keys shows the whole chain.

What an effect key does​

Press once to add the effect to your chain. Press again to remove it. The red border means that the effect is loaded. The row is therefore also a readout of the chain that you run.

An effect key is bound to the effect type, not to a position in the chain. This has two results. A new chain order in the Effects panel does not re-point your keys. A layout from one machine also works on another machine, because a key can name an effect that the second machine never loaded. The press loads it.

FXCanvas adds the effect to the end of the chain, and the effect starts enabled. This is the same result as an effect that you add in the Effects panel. For finer control, use FXCanvas itself. A new chain order, or a hidden effect that stays loaded, needs the Effects panel. The deck offers the one switch only.

Add Browse only where it helps​

Browse renders the content of the current folder page. The number of Browse keys that you place is the page size (1 to 32). This works well for small sets that change often, for example a new clip or a new camera. It works badly for large sets, because each page is a linear scan.

Large folders stay large. A folder of 30 source types is 30 items to page through. An alphabetic subdivision was tried and dropped, because it replaces one long scan with two short scans. The search still costs you time in the middle of a show. If you know which item you want, pin it.

Two Browse keys and a Navigate pair on one page, with all other keys pinned, works better than a deck of Browse keys.

Connection profile​

The connection profile holds the host, the port, and the optional API key that the plugin uses to reach FXCanvas. Edit it in the property inspector of any FXCanvas key. The profile is plugin-wide, so one edit applies to every key.

FieldRangeDefault
Host1–253 characters (name or IP address)127.0.0.1
Port1–655358080
API key0–256 characters, optionalempty (no authentication header)
Refresh intervaloff, 500, 1000, 2000, or 5000 msoff
Key roleNode rendering, up, next page, previous pageNode rendering
Item (Pin keys only)Any source, palette, or installable effectnothing pinned

Refresh interval is off by default. The keys still stay current. Source, preset, and palette previews are static until you edit them, so a timer gives no benefit. Each key re-reads its data on a press, and when the plugin requests a folder. Your next touch on the deck therefore shows the changes that you made in the FXCanvas UI. Set an interval only for two results. The first result is animated live-input previews on the key. The second result is borders that follow changes from elsewhere while nobody touches the deck.

To configure the profile:

  1. Select any FXCanvas key to open the property inspector. The profile is plugin-wide, so every action shows the same one.
  2. When the Stream Deck and FXCanvas run on the same computer, leave Host at 127.0.0.1 and Port at 8080. For a separate show machine, enter its address and the port from FXCanvas Settings → Remote Control.
  3. If you enabled authentication in FXCanvas, enter the API key. The plugin then sends it as X-API-Key on every request. When the field is empty, the requests carry no authentication header.
  4. If you do not know the port of FXCanvas, press Scan 127.0.0.1:8080-8089. The plugin tries each port for one second. It then lists the ports that answered, or reports that it found no FXCanvas instance.
  5. Save the profile. The plugin calls GET /api/v1/status at once. It shows the application name and version from the response in the inspector.
  6. For animated previews only, change Refresh interval from off. Then set the Key role on Navigate keys, or the Item on Pin keys.

The plugin rejects a value outside its range. The inspector names the field with the error, the last saved profile stays in force, and the plugin sends no request.

The state text on the keys shows the condition of the connection:

State textMeaning
OfflineFXCanvas did not answer within 2 seconds, or the host and port are unreachable. The plugin tries again after 2 seconds, and it doubles the wait up to 30 seconds.
AuthFXCanvas answered 401. The API key is missing or wrong.
ProThe connected FXCanvas has no active license, so the REST API is unavailable.
UpdateThe connected FXCanvas is too old to serve the browse and live-thumbnail routes.
TopYou are at the root folder, so the up key has no destination.
EmptyThe folder that you opened has no entries.

FXCanvas Remote Control settings​

The FXCanvas REST server must run before a key can render. Configure the server in Edit → Settings → Remote Control.

  1. Open Edit → Settings and select the Remote Control tab.
  2. Select Enable REST API Server.
  3. Leave Port at 8080 to match the plugin default. For another port, enter the same value in the property inspector.
  4. You can also set an API Key. If you set one, enter the same key in the property inspector. If the two keys differ, every key shows Auth.
  5. Click Apply. Then make sure that the status reads Server Running.
  6. For a Stream Deck on a different computer, use the Network Address from the same panel as the plugin host. Also permit the port through the firewall of the show machine.

The plugin uses these FXC_API routes: GET /api/v1/status, GET /api/v1/capabilities, GET /api/v1/browse, GET /api/v1/sources, GET /api/v1/sources/current, GET /api/v1/palettes, GET /api/v1/effects, and GET /api/v1/effects/available. It also uses the thumbnail routes, and the activation routes, which include POST /api/v1/effects/add and /remove. The REST server gives all of these routes. The Browse & Inputs API Reference documents the routes that this feature added. The Effects & Palettes API Reference documents the effect catalog and the palette colors.

Troubleshooting​

SymptomWhat to do
Every key shows OfflineMake sure that the REST server is enabled and reads Server Running. Make sure that the host and port match. Make sure that the port is open in the firewall.
Every key shows AuthThe API key in the property inspector must match the one in Settings → Remote Control exactly.
Every key shows ProThe REST API needs an activated license. See Licensing.
Every key shows UpdateUpdate FXCanvas. This build is older than the browse and live-thumbnail routes.
Keys show placeholder icons instead of previewsThe thumbnail request failed, or it timed out. Look in the Log Viewer in FXCanvas, and try a longer refresh interval.
Failed flashes on a key for 2 secondsFXCanvas rejected the activation, or the activation took more than 5 seconds. The previous source still drives the output.
Only some entries appear in a folderThe browse response omits unavailable devices, unavailable media files, and unsupported media files.
A root folder is missingFXCanvas omits a folder that has no children. Live Inputs appears after you attach a device.
A pinned key shows no red border while its item is liveOnly one source and one palette can be live at a time. Make sure that you pinned the item that runs. An effect border means that the effect is loaded in the chain, not that it is visible.
An effect key shows FailedThe chain is at the effect limit of your license tier, or the effect creation failed. Look in the Effects panel.
ISF sources is emptyThis FXCanvas build is older than the isf source type field, so FXCanvas lists every source type under Shader sources instead. You can still pin all of them.
A pinned key shows Pick…The key has no pinned item. Select the key and select an Item.