LLM JUMPSCARE - THIS PLUGIN WAS BUILT ALMOST EXCLUSIVELY WITH CLAUDE

Pogly Control puts your Pogly stream overlay on your Stream Deck. Switch layouts, show and hide elements, play and pause media, pop images and widgets onto the screen, and drive the widgets already on your canvas, without alt-tabbing away from your game. Every key shows what your overlay is actually doing, even when a teammate changes it from the Pogly editor.

How it works

The plugin talks to your overlay through the Pogly HTTP API, using an API token you create in Pogly. Your overlay and editor see every change instantly, exactly as if you had made it in the editor.

flowchart LR
    deck["Stream Deck<br/>(keys and dials)"] --> plugin["Pogly Control<br/>plugin"]
    plugin -- "API token" --> api["Pogly HTTP API<br/>(your overlay's module)"]
    api --> overlay["Overlay in OBS"]
    api --> editor["Pogly editor"]
    api -. "live key state, every 5 s" .-> plugin

Loading

Install

Platform	How
Windows / macOS	Install Pogly Control from the Elgato Marketplace, or double-click the .streamDeckPlugin file from this repository's Releases. Needs the Stream Deck app 6.9 or newer.
Linux	Use OpenDeck, which runs Stream Deck plugins on Linux. See Linux (OpenDeck) below.

Set up a connection

1. In Pogly, open Settings, API Access and generate an API token (not read-only).
2. Drop any Pogly Control action onto a key. The Connection dropdown sits at the top of its settings.
3. Click Create, then enter a nickname, your overlay URL (the one you use as your OBS browser source, e.g. https://cloud.pogly.gg/overlay?module=...), and the API token. Save.
4. Click Test. It confirms the connection and names any permission the token is missing.

Connections are shared by every Pogly Control key: set up each overlay once, then pick it per key. Run as many overlays from one deck as you like. Edit and Delete act on the connection selected in the dropdown (Delete asks for a second click, and keys that used it fall back to the first remaining connection).

A token can only do what the account that created it is explicitly allowed to do on that overlay. If Test warns about missing permissions, grant them to that account in Pogly, or create the token from an account that has them.

Tokens are stored in Stream Deck's local settings file in plain text, like any stream key. Revoke a token from Pogly if it ever leaks.

Actions

	Action	What it does	Pogly permission
	Set Active Layout	Switches the active layout (scene). The key shows the layout's name and lights up while it is live.	SetLayoutActive
	Element Show/Hide	Hides any element and brings it back at its previous opacity. The key shows the element's name and whether it is visible.	UpdateElement
	Media Play/Pause	Plays or pauses a media element, or restarts it from the beginning (per key). Works on keys and on Stream Deck + dials (press or touch).	UpdateElement
	Media Volume	Stream Deck + dial: turn to change a media element's volume, press or touch to mute and unmute.	UpdateElement
	Quick Text	Puts a preset text banner (text, size, color, position) on the active layout; press again to remove it.	AddElement, DeleteElement
	Image Pop	Pops an image or GIF from your Pogly library onto the overlay for a set number of seconds. Pressing again restarts the timer.	AddElement, DeleteElement
	Widget Pop	The same, for widgets: spawn one from your library for a few seconds and let its on-load logic run (a sound, an animation, an alert).	AddElement, DeleteElement
	Widget Toggle	Flips a toggle or boolean variable on a widget already on your canvas. The key shows the variable's current value.	UpdateElement
	Widget Button	Fires a widget's button variable, exactly like clicking it in the Pogly editor.	UpdateElement
	Widget Set Variable	Sets any text, boolean, color, slider, dropdown, datetime, counter, or list variable to a preset value.	UpdateElement

Every action also needs the token's account to be an editor (Whitelisted) on the overlay, which is what lets keys read and show live state. The Owner role covers everything.

Widget actions need Pogly 1.4.2 or newer on the overlay. They change only the chosen variable on the server, so live variables update the running widget in place, and a press can never overwrite someone else's edits to the widget. On an older overlay, the variable picker says the overlay needs updating.

Linux (OpenDeck)

Elgato's Stream Deck app does not run on Linux, but OpenDeck runs Stream Deck plugins there, including this one.

1. Install OpenDeck and its udev rules as described in its README.
2. Install Node.js 20 or newer from your distribution. OpenDeck starts the plugin with the system's Node (unlike Elgato's app, which bundles its own), and refuses anything older than 20. This applies to OpenDeck's Flathub build too: it uses the host's Node, and the Node.js Flatpak is not supported.
3. Download gg.pogly.streamdeck.streamDeckPlugin from this repository's Releases (Elgato Marketplace downloads are packaged for Elgato's app and may not load in OpenDeck) and install it from OpenDeck's Plugins tab.
4. Set up a connection exactly as above.

manifest.linux.json is an OpenDeck-only override that declares Linux support; Elgato's app ignores it.

Troubleshooting

Symptom	What to check
A key flashes a yellow triangle	The action failed. The plugin log names the reason (missing permission, deleted element, renamed variable).
Test warns about missing permissions	The token's account lacks them on this overlay. See the token note under Set up a connection.
Test says the module cannot be found	The overlay URL's ?module= value is wrong or incomplete. Copy the URL again from your OBS browser source.
Widget pickers say the overlay needs updating	The overlay runs a Pogly version older than 1.4.2.
Dial actions are missing from the action list	Stream Deck lists dial actions only when a dial slot is selected.

Logs: the plugin writes to %APPDATA%\Elgato\StreamDeck\Plugins\gg.pogly.streamdeck.sdPlugin\logs\ on Windows (open the newest file; a new one starts only once something is logged), and the Stream Deck app to %APPDATA%\Elgato\StreamDeck\logs\StreamDeck.log. On macOS, the same folders live under ~/Library/Application Support/com.elgato.StreamDeck/.

Development

npm install
npm run deploy   # build, copy into the Stream Deck plugins folder, restart the plugin
npm run pack     # build the .streamDeckPlugin into dist/

Script	Does
npm run icons	Renders the PNG action icons from the SVG sources in assets/icons/.
npm run readme-images	Renders the banner and figures in this README from the real key icons.
npm run marketplace-images	Renders the Elgato Marketplace app icon, thumbnail, and gallery images into marketing/marketplace/.

Notes for contributors:

• npm run deploy copies the built plugin instead of using streamdeck link: the SDK's log setup crashes when the plugin folder is a junction to another drive, which is what link creates when the repo is not on the same drive as %APPDATA%. Stream Deck's developer mode (npx streamdeck dev) must be on for the restart step; it resets when the app restarts.
• The manifest declares SDKVersion: 3 (required for Marketplace protection), which requires @elgato/streamdeck 2.x. A 1.x SDK refuses to start against it and the plugin silently crash-loops, so check the plugin log after any deploy.
• The SDK delivers the reply to getSettings() / getGlobalSettings() as a "settings changed" event too. Handlers for those events must never read settings or trigger a refresh unconditionally; doing so created request loops twice during development.
• Live key state comes from one shared poller (every 5 seconds, only while Pogly keys are on screen). Key presses trigger an immediate refresh, so the interval only has to catch changes made elsewhere.

Roadmap

• Layouts, element show/hide, media play/pause and volume, Quick Text
• Image Pop and Widget Pop
• Widget Toggle, Button, and Set Variable (Pogly 1.4.2+)
• Multiple overlays per deck (connection profiles)
• Linux via OpenDeck
• Stream Deck + dials for media
• Counter step and dropdown cycle actions for widgets