Overview

Erizos Studio supports integration with the Elgato Stream Deck for faster and more intuitive control.
This feature allows operators to trigger actions, send commands, and receive feedback directly on the Stream Deck device.

Below you will find examples of how to:

• set text labels on Stream Deck buttons,
• use Font Awesome Icons on buttons,
• handle button press events sent back from the device.

These examples use WebSocket payloads, making it easy to configure and customize the Stream Deck for your production workflow.

The Stream Deck integration is hosted by Agent as a standalone WebSocket server (separate from the Agent HTTP/API port). Clients can connect to this WebSocket to set key text/icons/images and receive button press events.

Enable the Integration

Agent only starts the Stream Deck WebSocket server when enabled in Agent settings.

On Windows the settings file is typically:

C:\ProgramData\Erizos\Agent\Settings.json

Add / edit:

{
  "streamDeck": {
    "enabled": true,
    "port": 5800
  }
}

Then restart Agent.

Connect to the WebSocket

Default URL:

ws://localhost:5800

The server accepts two equivalent message formats:

{ "type": "button_fill", "data": { "keyIndex": 0, "label": "Hello" } }

or

{ "body": { "type": "button_fill", "data": { "keyIndex": 0, "label": "Hello" } } }

Stream Deck Commands

Ping

{ "type": "ping" }

Response:

{ "type": "pong", "timestamp": "2026-02-04T12:00:00.000Z" }

Status

{ "type": "status" }

Response:

{
  "type": "status_response",
  "data": { "connected": true, "device": { "model": "...", "keyCount": 15, "serialNumber": "..." } },
  "timestamp": "2026-02-04T12:00:00.000Z"
}

Set Text Label on a Key (button_fill)

{
  "type": "button_fill",
  "data": {
    "keyIndex": 4,
    "label": "Example",
    "bgRgb": "#000000FF",
    "fgRgb": "#FFFFFF"
  }
}

Property	Description	Type	Default Value
keyIndex	key index to set (0 = top-left)	number	0
label	text to render on the key	string
bgRgb	background color (any CSS color string, commonly #RRGGBB or #RRGGBBAA)	string	#000000FF
fgRgb	text color (any CSS color string)	string	#FFFFFF

Set Font Awesome Icon on a Key (button_svg)

{
  "type": "button_svg",
  "data": {
    "keyIndex": 1,
    "name": "play",
    "style": "solid",
    "bgRgb": "#000000FF",
    "fgRgb": "#00ff7e"
  }
}

Property	Description	Type	Default Value
keyIndex	key index to set (0 = top-left)	number	0
name	Font Awesome icon name (e.g. play, pause)	string
style	Font Awesome style	string (enum: solid/regular/brands)	solid
bgRgb	background color (CSS color string)	string	#000000FF
fgRgb	icon color (CSS color string)	string	#FFFFFF

Set Image on a Key (button_image)

To set an image on a key, send a URL reachable from the Agent machine:

{
  "type": "button_image",
  "data": {
    "keyIndex": 2,
    "url": "https://example.com/logo.png",
    "bgRgb": "#000000FF",
    "padding": 2,
    "sizeRatio": 1
  }
}

Property	Description	Type	Default Value
keyIndex	key index to set (0 = top-left)	number	0
url	image URL (http/https)	string
bgRgb	background fill behind the image (CSS color string)	string	#000000FF
padding	padding in pixels around the image	number	0
sizeRatio	scales image area relative to key size (0.1 - 1)	number	1

Notes:

• Agent also accepts imageUrl or image instead of url.
• Images are downloaded by Agent (max ~5MB, ~10s timeout, up to 3 redirects).

Receiving Button Events

When a key is pressed or released, Agent broadcasts the following message to all connected WebSocket clients:

{
  "type": "button_event",
  "data": {
    "keyIndex": 0,
    "action": "down",
    "timestamp": "2025-09-10T12:13:44.343Z",
    "row": 0,
    "column": 0
  },
  "timestamp": "2025-09-10T12:13:44.343Z"
}

Property	Description	Type	Default Value
type	event type	string	button_event
data.keyIndex	key index (0 = top-left)	number
data.action	action taken	string (enum: up/down)
data.row	computed row index	number
data.column	computed column index	number
data.timestamp	when the action happened	DateString
timestamp	server timestamp (same value as data.timestamp)	DateString

Quick Client Example (Node.js)

// npm i ws
const WebSocket = require('ws');

const ws = new WebSocket('ws://127.0.0.1:5800');

ws.on('open', () => {
  ws.send(JSON.stringify({ type: 'status' }));

  ws.send(JSON.stringify({
    type: 'button_fill',
    data: { keyIndex: 0, label: 'TAKE', bgRgb: '#000000FF', fgRgb: '#00ff7e' }
  }));

  ws.send(JSON.stringify({
    type: 'button_image',
    data: { keyIndex: 1, url: 'https://example.com/logo.png', padding: 2, sizeRatio: 1 }
  }));
});

ws.on('message', (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.type === 'button_event') {
    console.log('Button event:', msg.data);
  } else {
    console.log('Message:', msg);
  }
});

ws.on('close', () => console.log('Disconnected'));
ws.on('error', (e) => console.error('WS error', e));