LinuxStreamDeck
GPL-3.0 · 65 actions · v0.3.4

Your Elgato Stream Deck,
finally at home on Linux.

Elgato ships software for macOS and Windows only. This is a GTK4 desktop application built around deep OBS Studio integration, with Twitch, Home Assistant, Key Lights and per-application audio native rather than bolted on.

Install it Browse the actions
The LinuxStreamDeck window: a 15-key virtual deck on the left and the key editor on the right.

Why this one

The Linux community has built several genuinely good Stream Deck projects and they deserve credit. These are the things this one does differently — not better at everything, different on purpose.

◉

OBS is the point, not a plugin

29 OBS actions with live feedback on the keys, plus a raw-request escape hatch that reaches 100% of the obs-websocket v5 protocol. The active scene lights up, recording turns red, a muted mic is marked.

▲

A deck that never lies to you

A key that cannot work is faded. A key whose action just failed is outlined in red. A measurement the machine does not report shows a dash, never a zero — because a zero is a claim.

✦

No plugin ecosystem to assemble

Twitch, Home Assistant, Elgato Key Lights, per-application audio, HTTP endpoints and machine monitoring are in the box. Nothing to install, nothing running under Wine.

◫

Works with no hardware plugged in

The on-screen grid mirrors the physical device, so you can configure and test every key — single, double and long press included — before the deck ever arrives.

⌘

Built for Wayland, not around it

Media through MPRIS, audio through PipeWire, shortcuts through ydotool. No faked media keys, no X11 assumptions, no privileges.

✧

Ready before you go live

A pre-flight check answers, on the deck itself, the question asked in the minute before streaming: microphones, cameras, disk, stream target — and says plainly what it could not check.

What it puts on the keys

Every key below is drawn by the application's own renderer, so this is exactly what the hardware shows.

OBS, with the state on the key

Scenes, recording, streaming, sources, filters, audio, transitions, the replay buffer, studio mode. The key shows what OBS is doing rather than what you last pressed, straight from obs-websocket events.

A scene key can even show a live thumbnail of what that scene is sending out — the fastest way to spot a dead capture card before you cut to it.

29 actionsLive feedbackRaw request
Five keys: an active Camera scene lit blue, an inactive Screen scene, a red Record key, a green Go live key badged LIVE, and a red muted Mic key.

Numbers that change on their own

CPU, memory, GPU load and temperature, network throughput, free disk space — read straight from the kernel, so they keep working with OBS closed. Keys colour themselves amber and then red as a value gets into trouble.

Plus countdown timers, a stopwatch, and a counter for the things you lose track of.

No OBS neededWarning coloursA dash, never a fake zero
Six keys: CPU 43 percent in green, CPU temperature 88 degrees in amber, GPU 97 percent in amber, 6.0 megabits upload, 2.9 gigabytes of disk left in red, and a counter labelled Deaths at 7.

Twitch, your house, and your lights

A Twitch key tells you how long somebody has been waiting — not how many messages there are, because a count says nothing about whether you are ignoring someone. It can sound, and it can flash the whole deck when headphones are not enough.

Home Assistant entities come from a dropdown of what your server really has. Elgato Key Lights are found on the network by themselves. And one generic HTTP action reaches anything else that speaks REST.

TwitchHome AssistantKey LightsAny HTTP endpoint
Six keys: a chat alert waiting two minutes with three unread, a clip key, a lit Home Assistant kitchen light, an office temperature of 21.4, a Key Light and an uptime value.

Audio the way a stream actually needs it

Mute the game without muting Discord. Turn the music down without touching the microphone. Move the whole session between speakers and a headset with one key.

And a soundboard: send a sound to the virtual microphone and pick it up in OBS, Discord or a call, so everyone hears it — you included.

Per applicationPipeWireVirtual microphone
Six audio keys: microphone, a red muted microphone, game volume up, a red muted Discord, a headset device switch and a sound effect.

Media, and what is playing

Transport over MPRIS, so one key works with Spotify, VLC, Firefox and mpv alike. Turn on show what is playing and the key fills with the album art and the artist.

The song title deliberately is not shown: at 96 px it either gets cut or is drawn too small to read, while the cover is recognisable before you read anything.

MPRISAlbum artOne key, every player
Five media keys: previous, a now-playing key filled with album art and the artist name, next, volume down and volume up.
The cover and the artist come from the player; this sleeve is invented for the picture

It tells you when something is wrong

A key whose every action needs OBS is faded while OBS is closed, so "not ready" stops looking like "idle". A key whose action just failed gets a red outline for a few seconds, because that is where you are looking.

Long sequences show RUN with a slow breathing halo while they are working. Folders group related keys without spending a page.

Faded when unusableRed on failureFolders
Five keys: a faded unavailable scene key, a key outlined in red after failing, a key showing RUN while working, a folder and a running countdown.

And when it is idle, it is worth looking at

Eleven coordinated full-deck screen savers, drawn across the real grid of whatever deck is connected, with their own brightness and idle delay. A physical deck also wakes with a short startup sequence that spells its name across the keys.

You choose what it leaves on screen after a clean exit, too: the firmware standby image, every key off, or one image of your own.

11 stylesAny deck shapeCustom exit image
The Hyperspace screen saver drawn as one coordinated image across a 15-key grid.
Hyperspace, one frame, across all fifteen keys at once

Every action, searchable

Search by what you want to do rather than by where it lives. Try mute, scene, temperature or clip. Press / from anywhere to jump here.

65 actions

Show a value

Home Assistant

Show what a Home Assistant entity reports, live on the key: a temperature, a door, whether the washing machine is running.

  • needs Home Assistant
  • Entity
  • Ask again
  • ha.state

Switch or run

Home Assistant

Turn a Home Assistant entity on or off, or run a scene or script. The key lights up while the entity is on.

  • needs Home Assistant
  • Entity
  • Do what
  • ha.switch

Light brightness

Lights

Make an Elgato Key Light brighter or dimmer, or set a level.

  • Light
  • Do what
  • Brightness (%)
  • light.brightness

Light on/off

Lights

Switch an Elgato Key Light on or off. The key lights up while the light is on.

  • Light
  • Do what
  • light.power

Light temperature

Lights

Make an Elgato Key Light warmer or cooler, or set a colour temperature between 2900K and 7000K.

  • Light
  • Do what
  • Temperature (K)
  • light.temperature

Change profile

Navigation

Switch to a selected profile and its own set of pages.

  • Destination profile
  • nav.profile.go

Go to page

Navigation

Switch directly to a selected page in the current profile.

  • Destination page
  • nav.page.go

Next page

Navigation

Switch to the next page, wrapping to the first page after the last.

  • nav.page.next

Page indicator

Navigation

Show which page is active. Pressing it does nothing, so it can sit next to the page navigation keys.

  • Show
  • nav.page.indicator

Previous page

Navigation

Switch to the previous page, wrapping to the last page from the first.

  • nav.page.previous

OBS hotkey

OBS · Advanced

Trigger any internal OBS hotkey by name.

  • needs OBS
  • Hotkey
  • obs.hotkey

OBS statistics

OBS · Advanced

Show a live measurement on the key: dropped frames, bitrate, stream or recording time, free disk space, CPU or FPS. System CPU and free disk space keep working while OBS is closed.

  • needs OBS
  • Measurement
  • Warn with color
  • Disk folder (free disk space)
  • obs.stats

Pre-flight check

OBS · Advanced

Check audio, cameras, disk, CPU, the stream destination and your Twitch title and category, and show the results across the whole deck. Reports only; changes nothing.

  • needs OBS
  • obs.preflight

Raw request (advanced)

OBS · Advanced

Send any obs-websocket v5 protocol request. 100% API coverage.

  • needs OBS
  • Request type
  • JSON payload
  • obs.raw

Mute input

OBS · Audio

The key lights up when the input is muted. The scene only narrows the list of inputs to choose from; muting applies to the input itself, on every scene.

  • needs OBS
  • Scene (narrows the list below)
  • Audio input
  • Mode
  • obs.mute

Raise/lower volume

OBS · Audio

The scene only narrows the list of inputs to choose from; the change applies to the input itself, on every scene.

  • needs OBS
  • Scene (narrows the list below)
  • Audio input
  • Change (dB, negative lowers)
  • obs.volume_adjust

Set volume

OBS · Audio

The scene only narrows the list of inputs to choose from; the change applies to the input itself, on every scene.

  • needs OBS
  • Scene (narrows the list below)
  • Audio input
  • Volume (dB)
  • obs.volume_set

Media control

OBS · Media

Control video/audio sources (Media Source, VLC).

  • needs OBS
  • Media source
  • Operation
  • obs.media

Add recording chapter

OBS · Recording & Streaming

Mark this moment in the recording so it is easy to find later. Needs OBS 30.2+ recording to hybrid MP4.

  • needs OBS
  • Chapter name
  • obs.record_chapter

Pause recording

OBS · Recording & Streaming

Pause or resume a recording in progress, without closing the file. The key lights up while it is paused.

  • needs OBS
  • obs.record_pause

Record on/off

OBS · Recording & Streaming

Start or stop recording. «toggle» switches between the two, so one key does both.

  • needs OBS
  • Mode
  • obs.record

Replay buffer on/off

OBS · Recording & Streaming

Start or stop the replay buffer, which keeps the last seconds of video in memory ready to be saved.

  • needs OBS
  • obs.replay

Save replay

OBS · Recording & Streaming

Save what the replay buffer is holding to a file, capturing the moment that just happened.

  • needs OBS
  • obs.replay_save

Source screenshot

OBS · Recording & Streaming

Save a PNG screenshot of a source or scene.

  • needs OBS
  • Source or scene
  • Destination folder
  • obs.screenshot

Split recording file

OBS · Recording & Streaming

Close the current recording file and carry on into a new one, without stopping. Needs OBS 30+.

  • needs OBS
  • obs.record_split

Stream on/off

OBS · Recording & Streaming

Start or stop the live stream. «toggle» switches between the two, so one key does both. The key turns green and shows LIVE while you are broadcasting.

  • needs OBS
  • Mode
  • obs.stream

Virtual camera on/off

OBS · Recording & Streaming

Start or stop the virtual camera, so OBS shows up as a webcam in Zoom, Meet, Discord and anything else.

  • needs OBS
  • obs.virtualcam

OBS profile

OBS · Scenes

Switch to another OBS profile, swapping its encoding, output and recording settings. This is an OBS profile, not a LinuxStreamDeck one.

  • needs OBS
  • Profile
  • obs.profile

Scene collection

OBS · Scenes

Switch to another OBS scene collection, swapping the whole set of scenes and sources at once.

  • needs OBS
  • Collection
  • obs.scene_collection

Set preview scene

OBS · Scenes

Put a scene in the studio mode preview. The key can show a live preview of what that scene is showing.

  • needs OBS
  • Scene
  • Live preview
  • obs.scene_preview

Set transition

OBS · Scenes

Choose the transition used between scenes, and optionally how long it lasts in milliseconds.

  • needs OBS
  • Transition
  • Duration (ms, 0 = keep)
  • obs.transition_set

Studio mode on/off

OBS · Scenes

Turn studio mode on or off, so scenes are staged in preview before going to program. The key lights up while it is on.

  • needs OBS
  • obs.studio_mode

Switch scene

OBS · Scenes

Switch the program scene. The key lights up when it is the active scene, and can show a live preview of what that scene is showing.

  • needs OBS
  • Scene
  • Live preview
  • obs.scene_switch

Transition (studio)

OBS · Scenes

Send the preview to program.

  • needs OBS
  • obs.studio_transition

Enable/disable filter

OBS · Sources & Filters

Enable, disable or toggle a filter applied to a source, such as a chroma key, a colour correction or a noise gate.

  • needs OBS
  • Source
  • Filter
  • Mode
  • obs.filter

Move/scale source

OBS · Sources & Filters

Change one transform property of a source in a scene. «adjust» adds to the current value, so a key can nudge it repeatedly.

  • needs OBS
  • Scene
  • Source
  • Property
  • Mode
  • Value
  • obs.transform

Refresh browser source

OBS · Sources & Filters

Reload a browser source, bypassing its cache.

  • needs OBS
  • Browser source
  • obs.browser_refresh

Set text source

OBS · Sources & Filters

Replace what a text source displays. Useful for a countdown message, a «back in 5» card or a now-playing line.

  • needs OBS
  • Text source
  • Text
  • obs.text

Show/hide source

OBS · Sources & Filters

Show, hide or toggle a source in a scene. Sources inside a group can be picked too. The key lights up while the source is visible.

  • needs OBS
  • Scene
  • Source
  • Mode
  • obs.source_visibility

Close application

System

Ask an application to quit, or force it to stop.

  • Application
  • Force close
  • sys.app.close

Countdown timer

System

Start a countdown shown as HH:MM:SS. Press again while it is running or after it finishes to stop and reset it. An optional sound can play on completion.

  • Timer duration (MM:SS)
  • Completion sound (optional)
  • Sound volume (%)
  • sys.timer

Counter

System

Count something on the key: deaths, takes, attempts. A press adds, and holding the key resets it. Give it a negative step to count down.

  • Each press adds
  • Starts at
  • sys.counter

Keyboard shortcut

System

Send a keyboard shortcut to the focused application. Pick a preset to fill in the shortcut, then edit it if your desktop uses another one.

  • Preset
  • Shortcut
  • sys.shortcut

Media action

System

Control the running media player through MPRIS, or the session volume.

  • Action
  • Show what is playing
  • sys.media

Open

System

Open a file, folder or program with the desktop's own handler.

  • File, folder or program
  • sys.open

Open application

System

Start an installed application, optionally closing it again with a long press.

  • Application
  • If it is already running
  • On long press
  • sys.app.open

Open URL

System

Open a web address in the default browser.

  • URL
  • sys.url

Play audio file

System

Play a local WAV, MP3, OGG, FLAC or Opus file. Send it to the virtual microphone and it becomes a soundboard: OBS, Discord or a call can pick that up and everyone hears it. A multiple-action sequence continues after playback finishes or reaches its time limit.

  • Audio file
  • Volume (%)
  • Maximum play time (optional)
  • Who hears it
  • sys.audio

Run command

System

Run a shell command in the background.

  • Command
  • sys.command

Shortcut switch

System

Alternate between two keyboard shortcuts, sending the next one on each press.

  • First shortcut
  • Second shortcut
  • sys.shortcut.switch

Stopwatch

System

Count elapsed time as HH:MM:SS. Press again to stop and reset it to zero.

  • sys.stopwatch

Switch audio device

System

Make a device the one the session uses. Choose a second device too and one key moves between them, which is what speakers and a headset want. The key lights up while its device is the one in use.

  • Device
  • And back to
  • sys.audio_device

System monitor

System

Show a live machine measurement on the key: CPU, memory, GPU, temperatures, network throughput or free disk space. None of it needs OBS.

  • Measurement
  • Network interface
  • Disk folder
  • Warn with color
  • sys.stats

Volume and mute

System

Change the volume of the speakers, the microphone or one application on its own. A mute key lights up while whatever it points at is muted.

  • What to change
  • Application
  • Do what
  • By how much
  • sys.volume

Wait

System

Pause for the given time (MM:SS) before the next action. Meant for multiple / toggle keys, between two actions.

  • Wait time (MM:SS)
  • sys.wait

Announce in chat

Twitch

Post a highlighted announcement in your own Twitch chat.

  • needs Twitch
  • Message
  • Highlight
  • twitch.announce

Chat and event alerts

Twitch

Light up when somebody is waiting on you: a chat message, a new follower, a subscription or a raid. Shows who it was, how long they have waited and how many are unread, with an optional sound. Press it to mark them seen.

  • needs Twitch
  • Watch for
  • Which chat messages
  • Sound
  • Volume
  • Flash the whole deck
  • Flash colour
  • twitch.alert

Create clip

Twitch

Clip the last few seconds of the stream, the same as the Twitch clip button. The channel has to be live.

  • needs Twitch
  • twitch.clip

Create stream marker

Twitch

Mark this moment in the Twitch broadcast so it is easy to find afterwards. Pairs with the OBS recording chapter marker.

  • needs Twitch
  • Note
  • twitch.marker

Raid a channel

Twitch

Offer a raid to another channel, or cancel one already offered. Twitch opens the countdown on your chat; it never moves anyone by itself.

  • needs Twitch
  • Action
  • Channel to raid
  • twitch.raid

Set stream category

Twitch

Change the Twitch category (the game). The name is looked up on Twitch when the key is pressed, so an approximate one still works.

  • needs Twitch
  • Category
  • twitch.set_category

Set stream title

Twitch

Change the title of the Twitch stream.

  • needs Twitch
  • Stream title
  • twitch.set_title

Start ad break

Twitch

Run an ad break of the chosen length. Only Twitch Affiliates and Partners can run ads; the key is faded for an account that cannot. The channel also has to be live, and Twitch enforces its own gap between breaks.

  • needs Twitch
  • Length
  • twitch.commercial

Twitch statistics

Twitch

Show a live Twitch measurement on the key: viewers, followers, stream uptime, or whether the channel is live.

  • needs Twitch
  • Measurement
  • Color the key
  • twitch.stats

Web request

Web

Call an HTTP endpoint and, if you want, show a value from its answer on the key. Covers anything that speaks REST: a home automation bridge, a webhook, a dashboard, your own server.

  • URL
  • Method
  • Headers
  • Body
  • Show the answer on the key
  • Value to show
  • web.request

Getting it working

From nothing to a deck you actually use, in the order it makes sense to do it.

1 Install

Download the .deb from the releases page and install it:

sudo apt install ./linux-stream-deck-X.Y.Z.deb
sudo ./packaging/refresh-appstream.sh   # so software centres see it

The package is Architecture: all — the pure-Python app plus two vendored dependencies, with GTK4, GStreamer, Pillow and the keyring coming from apt. It recommends ydotool, playerctl, pulseaudio-utils and avahi-utils; each one that is missing simply disables the keys that need it and says so.

USB permissions. Run sudo ./install-udev.sh once (the package does it for you) and replug the deck, or it will not open. Building from source instead? ./build.sh --apt then ./run.sh.

2 Connect OBS

In OBS: Tools → WebSocket Server Settings. Enable the server and copy the port and password. In LinuxStreamDeck, click the network button in the header and paste them.

Two menus, and it matters which. The header carries two three-dot ⋮ buttons and the guide below names them. The profile menu is the one beside the profile selector: profiles, backups, the service accounts, the log. The page menu is beside the page selector and holds only page operations.

The password goes to your desktop keyring, never to the configuration file and never into an export. The dot in the status bar turns green when it is connected, and the app reconnects on its own if OBS restarts.

3 Your first key

  • Click any key on the grid. The editor opens on the right.
  • Pick a category and an action — or press the magnifier beside the action list and search every action at once, by name or by what it does.
  • Fill in the parameters. Dropdowns fill live from OBS, from your audio devices, from your Home Assistant entities.
  • Under Icon, keep the action's default, pick one of ~7,400 built-in icons, or use your own image.
  • Press Test to run it without touching the hardware, then Save.
Leaving the icon empty is not "no icon" — it means inherit, so the key follows the action's own picture and keeps following it if you change the action. The same is true of the label size and colour.

4 Key types

TypeWhat it does
Single actionOne action, with live state feedback on the key.
Multiple actionsA list run in order. Insert a Wait action to pause between them.
Toggle (ON/OFF)Two lists and a state, with its own look per state.
Random actionPicks one of its actions at each press.
Single / double / long pressA separate list per gesture.
FolderOpens its own grid of keys, nested up to five levels.

Any step in a list can be given a name, and the list shows that instead of the action, which is what keeps a long sequence readable. Steps reorder by dragging their handle, and copy between lists, key types and keys.

A list can also be told what a failure should do: carry on, or stop there. Stopping is right when the list is a recipe — "switch scene, wait, start recording" must not record the wrong scene.

5 Pages and folders

  • Profiles keep their own pages and keys: Streaming, Work, Gaming. Switch from the header or from the status icon.
  • Pages are added, renamed, duplicated, reordered and deleted from the page menu. Assign keys to go to a named page, or step forward and back.
  • Folders group related keys inside one key. Double-click a folder on screen to go in; the first key inside is always Back.

Drag a key onto an empty slot to move it, or onto another key to swap them. Hold a drag over a folder for about a second and it springs open, so you can drop the key inside; holding over Back comes out again. Ctrl+Z takes back a clear, a paste or a move.

6 Twitch

profile menu → Twitch account…, then read the code off the dialog and type it at twitch.tv/activate. No password is ever asked for and the tokens live in your keyring.

You then get: viewers, followers and uptime on a key; set the title or the category; clips; stream markers; ad breaks; raids; announcements. And the alert key, which shows how long somebody has been waiting — filterable down to questions and mentions, or to first-time chatters, so it keeps meaning something on a busy channel.

Disconnecting revokes the token, which is all any application can do. Twitch has no API to remove an app from your Connections page — only you can, and the dialog says so and links there.

7 Home Assistant

profile menu → Home Assistant…. You need the address (http://homeassistant.local:8123 usually works) and a long-lived access token: in Home Assistant, click your user name at the bottom of the sidebar → Security → Long-lived access tokens → Create token. Copy it immediately, it is shown once.

The entity dropdown then fills with what your server really has. One key turns a light, a switch, a fan, a media player, a scene or a script on, off or over; another shows what an entity reports.

8 Audio and soundboard

  • Volume and mute — point it at the speakers, the microphone, or one application on its own. A mute key lights up red while whatever it watches is muted, and follows changes you make elsewhere.
  • Switch audio device — set the device in use; give it a second one and the key moves between them.
  • Play audio file — and set who hears it to the virtual microphone to make it a soundboard.
For a soundboard key, pick Monitor of LinuxStreamDeck as an input in OBS, Discord or your call. The sound also comes out of your own speakers, so a key never feels dead.

9 Screen saver and exit display

The Stream Deck display button in the header holds both. Choose one of eleven animations, an idle delay and a brightness of its own — and preview it immediately, with or without hardware connected.

The same dialog sets what the physical deck shows after a clean exit: the firmware standby image, every key off, or one image of yours across the whole grid.

10 Backup and sharing

Every save writes a backup, and timestamped copies are kept — profile menu → Restore a backup… lists them with what each one holds.

Export the whole configuration as a .lsdconfig bundle that carries your icons, your audio files and your exit image, or right-click one key and export just that as a .lsdkey. Passwords, API keys and tokens are never exported: a machine you move to enters its own.

11 If something is wrong

What you seeWhat it means
The deck never appearsUSB permissions. sudo ./install-udev.sh, then replug it. The status bar says so after the second failed attempt.
A faded keyEvery action on it needs a connection that is not there — OBS closed, no Twitch account, no Home Assistant.
A key outlined in redIts action failed just now. The status bar says why, and the full reason is in the log.
A key showing --The measurement is not available on this machine. A zero would be a claim; a dash is the truth.
A dropdown that is emptyWhatever fills it could not be asked. The field stays typable so you can enter a value by hand.
Scenes renamed in OBSprofile menu → Check keys against OBS…. It lists what no longer resolves and repoints them, saving a backup first.

The full log lives at ~/.config/linuxstreamdeck/linuxstreamdeck.log and opens from the profile menu. That is the thing to attach to a bug report.

Supported hardware

The layout is read from the device, so screen savers, the startup sequence and a custom exit image are laid out across whatever grid you really have.

DeviceKeysGridStatus
Stream Deck Mini63 × 2Verified in simulation
Stream Deck Neo84 × 2Verified in simulation
Stream Deck Original / MK.2155 × 3Tested on real hardware
Stream Deck +8 + 4 dials + LCD strip4 × 2Verified in simulation
Stream Deck XL328 × 4Verified in simulation
Stream Deck Pedal3no displaysNot supported, and says so
Being straight about this: only the 15-key Original has been run on real hardware. Every other model is covered by an automated simulation of its real geometry, which is not the same thing. If you have one of the others, a bug report is genuinely useful.