Skip to main content

Elgato Stream Deck Developer Guide

What this guide covers

This guide explains how to build Stream Deck plugins quickly, when to use the official JavaScript/TypeScript SDK, when Python is the better local-control path, and where .NET/C# fits for native plugin authors.

Source scope as of July 1, 2026

The primary plugin path is based on Elgato's Stream Deck SDK 2.0.0 documentation, the official elgatosf/streamdeck repository, the Stream Deck CLI documentation, python-elgato-streamdeck, and StreamDeckToolkit. Product requirements and Marketplace rules change, so verify the linked sources before publishing.

1. The short version​

Use TypeScript with the official Elgato SDK for normal Stream Deck plugins.

Use Python with python-elgato-streamdeck when you want to control the physical device directly, usually without the official Stream Deck app.

Use C#/.NET when you need native-plugin architecture, existing .NET business logic, or Windows-heavy integrations and are comfortable with a less current ecosystem than Elgato's official Node.js path.

Avoid the raw WebSocket protocol unless you have a strong reason. Elgato documents it for native console apps, but explicitly frames native plugins as advanced and recommends the Node.js SDK for most developers.

2. Paths through this guide​

GoalStart hereWhy
Build a Marketplace-ready pluginJavaScript and TypeScript PluginsOfficial SDK, CLI, scaffold, build, watch, pack
Decide between JS, Python, and C#Architecture and SDK MapCompares plugin SDKs, direct HID, native plugins, and UI choices
Build a local automation panelPython HID AutomationDirect device control, key images, callbacks, brightness
Add user-configurable plugin settingsManifest and Property InspectorsAction metadata, settings, HTML inspectors, UI library
Prepare a plugin for deliveryPackaging and DistributionValidation, .streamDeckPlugin, Marketplace, DRM readiness
Debug weird behaviorTroubleshooting ChecklistPlugin visibility, hot reload, permissions, logs, device conflicts

3. Mental model​

A Stream Deck project can be one of two very different things:

ModelRuntimeUser experienceBest language
Stream Deck pluginRuns under the Stream Deck desktop appUser installs a plugin, adds actions to profiles, configures property inspectorsTypeScript / JavaScript
Direct device controllerTalks to the hardware directly over HIDYour app owns the deck and draws every key/screen statePython

Most confusion comes from mixing those models. Python can be excellent for controlling the hardware, but it is not the fastest way to produce a normal Stream Deck Marketplace plugin. The official SDK gives you the Stream Deck app integration, manifest conventions, property inspector path, packaging workflow, and Marketplace-ready structure.

4. Current official baseline​

Elgato's current SDK and CLI docs list these practical requirements:

  • Node.js 24 or newer for current SDK/CLI development.
  • Stream Deck app 7.1 or newer.
  • A Stream Deck device, or Stream Deck Mobile for testing when hardware is not available.
  • @elgato/cli for scaffolding, linking, restarting, validating, and packaging plugins.
  • A reverse-DNS plugin UUID, such as com.example.timer.

The scaffold generated by streamdeck create produces a source tree with src/, a compiled *.sdPlugin/ directory, manifest.json, ui/, imgs/, build scripts, and a watch workflow.

nvm install 24
nvm use 24
npm install -g @elgato/cli@latest
streamdeck create
cd my-plugin
npm run watch

Then change one action at a time:

  1. Edit the action implementation in src/actions/.
  2. Keep the action UUID stable.
  3. Update the title, image, or settings from the action event.
  4. Add a property inspector only when the action needs user configuration.
  5. Run streamdeck validate before packing.
  6. Run streamdeck pack *.sdPlugin when the plugin is ready to distribute.

6. Directory map​

docs/tools/streamdeck/
├── index.mdx
├── architecture-and-sdk-map.mdx
├── javascript-typescript-plugins.mdx
├── python-hid-automation.mdx
├── dotnet-native-plugins.mdx
├── manifest-property-inspector.mdx
├── packaging-distribution.mdx
└── troubleshooting-checklist.mdx

7. Primary references​