VR Deck · for plugin developers

VR Deck live pictures: a guide for plugin developers

VR Deck shows a Stream Deck owner's keys inside a SteamVR headset, lined up on the real deck. Keys of other plugins appear with the picture and title the Stream Deck app has on file for them, because plugins cannot see each other's pictures. If your plugin changes a key's picture or title while it runs (a clock, a counter, a meter, a status light, now-playing art), you can hand VR Deck that picture too, and the headset shows it live. It takes a few lines of code, and it changes nothing for users who do not run VR Deck.

1. The request
2. How long a live picture stays
3. Example (Stream Deck SDK, Node.js)
4. What VR Deck does with it

The request

POST http://127.0.0.1:28788/v1/key
Content-Type: application/json

{"plugin": "com.example.myplugin", "device": "<action.device.id>", "column": 2, "row": 1,
 "image": "data:image/png;base64,iVBORw0KGgo...", "title": "12:34"}

Send image, title or both. A field you leave out keeps its last live value (also while a request is held: a picture and a title sent as two requests are drawn together).

Every answer is JSON with "api": 1:

GET http://127.0.0.1:28788/v1 tells what the endpoint accepts: {"ok": true, "api": 1, "app": "VR Deck", "version", "key": "POST /v1/key", "formats", "maxImageBytes", "maxImageSide", "maxTitleChars", "maxRequestsPerSecond", "pendingMs"}.

How long a live picture stays

Until you send another one, or null; until the key leaves the page VR Deck shows (a page or profile switch); until another action takes the key's place; until the deck is unplugged; until the user switches live pictures or the whole-deck mirror off; or until VR Deck restarts. So send the current picture whenever your key appears (most plugins already set it in their willAppear handler). For a key whose picture rarely changes, send it again every 10 s or so while it is visible, so a VR Deck started after your plugin catches up; VR Deck skips a picture it already shows. VR Deck redraws a key at most every 200 ms: sending faster only replaces the picture that is waiting. A picture that arrives while the old page is still shown, and lands on your plugin's key at that spot of the old page, moves to your key on the new page when the switch reaches VR Deck (within 2 s).

Example (Stream Deck SDK, Node.js)

// VR Deck live pictures (optional): shows a key's live picture / title in the VR Deck headset overlay.
// Does nothing when VR Deck is not running; after a failed connection it waits 30 s before the next try (an answer
// such as 202 or 429 is not a failure).
const VR_DECK = "http://127.0.0.1:28788/v1/key";
const PLUGIN_UUID = "com.example.myplugin"; // your manifest's UUID
let vrDeckQuietUntil = 0;

export function toVrDeck(
	action: { controllerType: string; device: { id: string }; coordinates?: { column: number; row: number } | undefined },
	picture: { image?: string | null; title?: string | null }
): void {
	const c = action.coordinates;
	if (action.controllerType !== "Keypad" || !c || Date.now() < vrDeckQuietUntil) return;
	fetch(VR_DECK, {
		method: "POST",
		headers: { "Content-Type": "application/json" },
		body: JSON.stringify({ plugin: PLUGIN_UUID, device: action.device.id, column: c.column, row: c.row, ...picture })
	}).catch(() => {
		vrDeckQuietUntil = Date.now() + 30_000;
	});
}

Next to the calls you already make:

await ev.action.setImage(png);
toVrDeck(ev.action, { image: png }); // png = "data:image/png;base64,..."

await ev.action.setTitle(text);
toVrDeck(ev.action, { title: text });

fetch is built into Node.js 18 and later (the Stream Deck app's Node.js 20 included). Any language works: it is one JSON POST to 127.0.0.1. A quick test from PowerShell, with a device id and key of your own plugin:

Invoke-RestMethod -Method Post -Uri http://127.0.0.1:28788/v1/key -ContentType application/json -Body '{"plugin":"com.example.myplugin","device":"<device id>","column":0,"row":0,"title":"hi"}'

What VR Deck does with it

• It listens on 127.0.0.1 only, so nothing outside the PC can reach it, and it takes pictures and titles, never commands: nothing it receives presses, types or moves anything.
• It draws on a key only when the Stream Deck profile records that key's action as belonging to the plugin named in the request, and only while the key is on the page VR Deck shows. The keys on the deck itself are not touched.
• Requests from web pages are refused (the Origin and Host checks), so a website open in a browser cannot draw on your keys.
• Pictures and titles are kept in memory only and go to VR Deck's own companion on the same PC, which draws the headset overlay. The plugin log notes which plugins send (plugin UUID, the start of the deck id, the key) and why a request was refused, at most 30 lines a minute, never the pictures or titles.
• Any program on the PC can name any plugin's UUID. The most it can do is change how mirrored keys look in the headset (picture and title only), or crowd out other plugins' live pictures by flooding the endpoint; it cannot press, type or change anything on the deck.
• Your requests go to whatever program listens on 127.0.0.1:28788: normally VR Deck (GET /v1 says so), but a program that took the port first would get them. Send nothing you would not show on the key itself.

Users can switch it off with "livePictures": false in %LOCALAPPDATA%\VRDeck\settings.json, or move it to another port with "livePicturesPort" (1024 to 65535; your plugin then finds nothing at 28788, which costs nothing with the snippet above). Changes take effect within about 10 s.