streamrs

A lightweight Rust Stream Deck toolkit for Linux.
About · Download · Documentation · Developing

About

streamrs is a lightweight Stream Deck toolkit focused on a simple Linux-first workflow for configuring keys, icons, and actions on Stream Deck hardware.

It is built for and tested on:

• Elgato Stream Deck MK.2
• USB ID 0fd9:0080

Feature highlights:

• Static icons: PNG, JPEG/JPG, SVG
• Animated icons: GIF, APNG, animated WebP
• Built-in clock icon (clock.svg)
• Status-driven toggle icons via polling commands
• Keyboard shortcut actions
• Automatic pagination when config has more than 15 keys

Download

Install a release .deb (recommended on Debian/Ubuntu):

Release files are published on the GitHub Releases page:

• https://github.com/EriksRemess/streamrs/releases

sudo apt install ./streamrs_<version>_amd64.deb

Quick start after install:

1. Plug in the Stream Deck
2. Open the GUI: streamrs-gui
3. Edit buttons and save

Service behavior:

• On install, streamrs.service is enabled and started for active logged-in regular users
• On package upgrade, the service is restarted for active logged-in regular users
• To enable it for an additional user later, log into that user and run:

systemctl --user enable --now streamrs.service

• On each service start/restart, streamrs --init --force-images runs first:
  • creates a config if missing
  • refreshes bundled images from the package
  • keeps your existing config unless you explicitly run streamrs --init --force

Documentation

Running and Service Management

Open the GUI configurator:

streamrs-gui

Manually start the daemon (if you do not want to use the service):

streamrs

Useful service commands:

systemctl --user status streamrs.service
systemctl --user restart streamrs.service
systemctl --user stop streamrs.service

Profiles and File Locations

Default profile files live in:

• Config: ~/.config/streamrs/default.toml
• Images: ~/.local/share/streamrs/icons/
• Runtime state: ~/.local/state/streamrs/state.toml

Additional profiles use:

• ~/.config/streamrs/<name>.toml
• Shared icons in ~/.local/share/streamrs/icons/

Notes:

• If the config is missing, streamrs auto-initializes the profile from bundled defaults
• streamrs --init --force refreshes config and bundled images from package defaults
• Runtime state such as persisted portal permission restore tokens is stored separately from editable profile config

CLI Basics

Common streamrs flags:

• --profile <name>: use another profile
• --config <path>: use a custom config file
• --debug: inherit child process stdout/stderr
• --init: initialize profile files and exit
• --force: with --init, overwrite existing config/images

Actions

Each key can either launch a command or trigger a keyboard shortcut.

Example command action:

[[keys]]
action = "open https://github.com/EriksRemess/streamrs"
icon = "github.png"

Example keyboard shortcut action:

[[keys]]
shortcut = "Ctrl+Shift+T"
icon = "shortcut-example.png"

Notes:

• If both action and shortcut are set, shortcut takes precedence
• Shortcuts support common modifiers and keys such as Ctrl, Alt, Shift, Meta, function keys, arrows, Return, and single characters
• On GNOME Wayland, shortcut injection uses the RemoteDesktop portal and may show a permission prompt the first time
• If the portal backend grants persistence, streamrs stores the restore token in ~/.local/state/streamrs/state.toml to reduce future prompts

Status Buttons

Status buttons can poll a shell command and swap icons based on its exit code.

Example:

[[keys]]
action = "playerctl play-pause"
status = "playerctl status | grep -q Playing"
status_interval_seconds = 5
icon_on = "pause.png"
icon_off = "play.png"

Notes:

• status_interval_seconds controls the regular polling interval in seconds
• Existing status_interval_ms values are still supported for older configs
• Pressing a button with an action triggers a status refresh 1 second after the action command succeeds

Preview Renderer

Generate a mock image from your current profile:

streamrs-preview --output mock.png

Render a specific profile:

streamrs-preview --profile test --output mock.png

Notes:

• If --output is omitted, it writes mock.png
• If --profile is omitted, it uses the current profile from ~/.config/streamrs/current_profile (or default if unset)
• It reads the selected profile config and shared icons first, then falls back to packaged defaults if needed

Icon Composer

Create a Stream Deck icon from a logo (.svg or .png):

streamrs-icon-compose path/to/logo.svg

Defaults:

• Output directory: ~/.local/share/streamrs/icons/
• Output name: <logo>-icon.png (auto-suffixed if needed)

Options:

• --output <path>
• --padding <ratio> (0.0..0.5)

Developing

Developer-focused setup, source builds, packaging, maintainer notes, and contribution guidance are in development.md.

Credits

• Icon pack source: https://marketplace.elgato.com/product/hexaza-3d4ed1dc-bf33-4f30-9ecd-201769f10c0d

License

MIT. See LICENSE.