Stream Deck OBS Plugin: Every Action and Fixes When It Won’t Connect

The Stream Deck OBS plugin is Elgato’s free “OBS Studio” plugin that turns Stream Deck keys into live OBS controls: scene switching, recording, mic mutes, replay saves, filters and more, with keys that light up to show what is live. If it will not connect, the cause is almost always the small companion file the plugin places inside OBS, not your network or a WebSocket password, because Elgato’s official plugin talks to OBS through its own native bridge rather than through the built-in obs-websocket server.

This guide covers what every action in the stream deck obs plugin does, how to build useful button layouts, and how to fix the “Waiting for OBS” and warning-triangle problems step by step. If you only need a first-time walkthrough, our separate Stream Deck OBS setup guide covers the basic connection; this page goes deeper into the plugin itself.

What the Stream Deck OBS Plugin Actually Is

There are two families of tools people mean when they search for an “obs stream deck plugin”:

1. Elgato’s official OBS Studio plugin. Free on Elgato Marketplace, made by Elgato, available for Windows and macOS. When you install it, it also drops a companion component into OBS so the two programs can talk directly. This is the plugin most people use and the one this guide focuses on.
2. Third-party OBS plugins. Community plugins such as BarRaider’s OBS Tools and StreamDeck OBS+ connect through obs-websocket, the remote-control server built into OBS Studio 28 and newer. These need the WebSocket server switched on, the right port (4455 by default for WebSocket 5.x) and the password.

Mixing up the two is the root of a lot of bad advice. If you use Elgato’s plugin, typing a WebSocket password into OBS will not fix a “Waiting for OBS” key, because that plugin never uses the WebSocket server in the first place. According to an Elgato help article about OBS Studio 28, the company rebuilt its OBS-side plugin when OBS moved to the Qt6 interface framework, and the old Qt5 file can trigger an incompatibility warning if it is left behind.

Every Action in the Elgato OBS Studio Plugin

Elgato’s help center lists 19 actions. Here is what each one does and when it earns a key on your deck.

Core show controls

• Scene: switches to a chosen scene instantly. Drag it onto a key and pick the scene from the dropdown in the property panel.
• Stream: starts or stops your broadcast. The key shows whether you are live.
• Record: starts or stops a local recording. It has an optional Long Press setting that requires you to hold the key for 5 seconds, which prevents an accidental stop mid-session.
• Record Pause: pauses a recording without ending the file, handy for breaks.
• Chapter Marker: drops a marker into the recording so you can find highlights while editing. This depends on a recording format and OBS version that support chapters.
• Virtual Camera: turns the OBS virtual camera on or off for video calls.

Audio and sources

• Audio Mixer: mutes or unmutes a specific audio source, such as your microphone or desktop audio. The key turns red when muted, which is the most useful live feedback on the whole deck.
• Source Visibility: shows or hides a source in a scene, such as a webcam frame, a “be right back” image or an alert overlay.
• Filter: toggles a filter on a source, for example a noise suppression filter, a color correction pass or a blur.
• Media Source Control: plays, pauses, restarts or stops a media source such as an intro video.
• Screenshot: captures a still of the program output or a chosen source.

Replays, transitions and studio mode

• Replay Buffer: toggles the replay buffer on or off. The buffer must first be enabled in OBS under Settings > Output > Replay Buffer.
• Replay Buffer Save: saves the last stretch of footage held in the buffer, the length you set in OBS.
• Studio Mode: toggles Studio Mode so you can stage a scene in preview before it goes live.
• Preview to Program: pushes the staged preview scene live.
• Transition: sets which transition OBS uses (Cut, Fade, Stinger and so on).
• Scene Transition: switches to a scene using a specific transition.

Profiles and collections

• Profile: switches OBS profiles, which hold output settings such as bitrate and resolution. Useful if you keep a “Twitch 1080p60” and a “local 4K recording” profile.
• Scene Collection: swaps the entire set of scenes, for example between a gaming layout and a podcast layout.

Elgato notes that the Record Pause, Replay Buffer, Replay Buffer Save, Scene Collection, Media Source Control, Studio Mode, Preview to Program and Filter actions arrived with version 2.0 of the integration. If you do not see them, update the plugin from the Stream Deck app.

How to Install and Connect the Plugin

1. Update both apps first. Install the latest Stream Deck software and the latest OBS Studio. The plugin’s OBS-side file is built for specific OBS versions, so mismatched versions are the leading cause of trouble.
2. Close OBS. The companion file is copied into OBS’s plugin location during install, and OBS only loads plugins at launch.
3. Install the OBS Studio plugin. In the Stream Deck app, open Elgato Marketplace (the store icon), search for OBS Studio and install it. You will see an “OBS Studio” category appear in the actions list on the right.
4. Launch OBS normally. Not as administrator unless the Stream Deck app also runs as administrator; the two need the same permission level to see each other.
5. Drag a Scene action onto a key. If the scene dropdown fills with your scenes, the connection works. If it says “Waiting for OBS” or stays empty, jump to the troubleshooting section below.
6. Add an Audio Mixer key for your mic. Mute and unmute it once from the key and once from OBS to confirm the state syncs both ways.

Stream Deck Not Connecting to OBS: Fixes in Order

Work through these in order. Each step explains why it matters, so you can skip the ones that clearly do not apply.

1. Restart OBS, then the Stream Deck app. The plugin connects when OBS starts. If OBS was already open when you installed or updated the plugin, nothing will link until OBS restarts.
2. Update the plugin after every OBS update. OBS major releases (OBS 28, 29.1 and 32 are examples Elgato documents) changed how plugins load. Elgato’s help center describes a separate StreamDeckPluginOBS32 file for OBS Studio 32 and newer, so an old plugin version can silently fail on a new OBS.
3. Remove leftover old files. If OBS shows a warning about an incompatible StreamDeckPlugin on start-up, Elgato’s instructions are to delete StreamDeckPlugin.dll and StreamDeckPlugin.pdb from the OBS plugins folder (on Windows, the default is C:\Program Files\obs-studio\obs-plugins\64bit\). The newer Qt6 file stays in place and keeps working.
4. Fix portable OBS. Portable OBS 29.1 and later no longer loads system-installed plugins. Elgato’s fix is to copy the plugin files (StreamDeckPluginQt6.dll and .pdb, plus the OBS32 files on OBS 32 or newer) from C:\ProgramData\obs-studio\plugins\StreamDeckPlugin into the portable install’s plugin folder. Manually copied files do not auto-update, so repeat this after plugin updates.
5. Match permission levels. If OBS runs as administrator (common when people want game capture to work in anti-cheat titles) and Stream Deck does not, Windows can block them from talking. Run both normally, or both as administrator.
6. Check you have only one OBS running. A second instance in the system tray, or a leftover crashed process in Task Manager, can grab the connection.
7. Reinstall the plugin. Uninstall OBS Studio from the Stream Deck app’s plugin list, close OBS, reinstall from Marketplace, then open OBS. This rewrites the companion file cleanly.
8. Re-pick actions after renaming scenes. Scene, Source Visibility and Filter keys store names. Rename a scene in OBS and the key points at nothing; it is not a connection issue, just a stale target.

If you use a WebSocket-based third-party plugin

Third-party OBS plugins fail for different reasons. In OBS, open Tools > WebSocket Server Settings, tick Enable WebSocket server, note the port (4455 for WebSocket 5.x; 4444 belongs to the old 4.x add-on) and click Show Connect Info to copy the exact password, which is case-sensitive. Use 127.0.0.1 as the address when OBS runs on the same PC, and allow OBS through Windows Defender Firewall if you control OBS on a second computer. An older plugin written for WebSocket 4.x will connect and drop immediately against OBS 28 or newer; update it or switch to a 5.x-compatible plugin.

Button Recipes Worth Building

Multi Actions let one key fire several actions in sequence, and Elgato’s own example is a single key that switches to a “starting soon” scene, starts background music and mutes your microphone. These layouts suit most streamers:

Add a short Delay step (Stream Deck has a built-in Delay action under Multi Action) between scene changes and stream start or stop. Without it, the stream may end before the outro transition finishes rendering.

A sample 15-key layout

On a 15-key deck, a practical split is five scene keys across the top row, five audio and source keys in the middle (mic mute, desktop audio mute, music mute, webcam visibility, alerts visibility), and five show keys on the bottom (Go Live, BRB, Back, Clip It, End Show). Put Record and Stream on Long Press if you have ever stopped a stream by accident.

Which Stream Deck Works Best With OBS

Every current Stream Deck model runs the same OBS plugin. What changes is how many controls fit on one page and whether you get dials for audio.

Gear That Helps

• Elgato Stream Deck MK.2: 15 LCD keys · swappable faceplate · detachable USB-C cable. The sweet spot for a single page of OBS controls.
• Elgato Stream Deck +: 8 LCD keys · 4 push dials · touch strip. Dials map well to the OBS audio mixer for live volume changes.
• Elgato Stream Deck XL: 32 LCD keys · USB connection · folder support. For productions with many scenes, cameras and sources.
• Elgato Stream Deck Neo: 8 LCD keys · 2 touch points for page switching. A compact entry point for basic scene and mute control.

Frequently Asked Questions

Does the Elgato stream deck obs plugin need obs-websocket?

No. Elgato’s official OBS Studio plugin uses its own native component inside OBS, so you do not need to enable the WebSocket server or set a password for it. WebSocket settings only matter for third-party plugins that are built on obs-websocket.

Why does my Stream Deck say “Waiting for OBS”?

The plugin cannot see a running, compatible OBS. Restart OBS after installing or updating the plugin, make sure both apps run at the same permission level, and update the plugin after any OBS major update. Portable OBS 29.1 and later also needs the plugin files copied in by hand.

Is the OBS plugin for Stream Deck free?

Yes. Elgato’s OBS Studio plugin is free on Elgato Marketplace for Windows and macOS. Many third-party OBS plugins are free too, though some ask for an optional donation.

Can Stream Deck control OBS on a second PC?

Elgato’s plugin is designed for OBS on the same computer as the Stream Deck app. For a two-PC setup, use a WebSocket-based plugin pointed at the streaming PC’s local IP address and port 4455, and allow OBS through the firewall on that machine.

Why did my scene keys stop working after I renamed scenes?

Scene, Source Visibility and Filter actions store the name you picked. After renaming in OBS, open each key’s settings in the Stream Deck app and pick the new name from the dropdown.

Does the plugin work with Streamlabs Desktop?

No, the OBS Studio plugin targets OBS Studio. Streamlabs Desktop has its own separate Stream Deck plugin on Elgato Marketplace, so install that one instead if Streamlabs is your broadcast app.