Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions .ensemblr/settings.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
#:schema https://www.ensemblr.dev/schemas/settings.schema.json

# Every command runs against this worktree's flake (`.`).

[scripts]
# Build the dev shell and fill the Go module cache, so a new workspace's first
# build or lint does not wait on downloads.
setup = "nix develop -c go mod download"

# Build and test the package for this machine and evaluate the other systems.
[scripts.run.check]
command = "nix flake check"
icon = "shield-check"
default = true

# Build the package into ./result.
[scripts.run.build]
command = "nix build"
icon = "hammer"

# Drive the attached Stream Deck from decks/test.deck until stopped. -verbose
# prints every key press and the output of the exec key.
[scripts.run.deck]
command = "nix run . -- -deck decks/test.deck -verbose"
icon = "play"

# Lint the Go sources with golangci-lint and .golangci.yml, in the dev shell.
[scripts.run.lint]
command = "nix develop -c golangci-lint run ./..."
icon = "list-checks"

# Format every Nix file with alejandra, the flake's formatter.
[scripts.run.format]
command = "nix fmt -- ."
icon = "paintbrush"
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,6 @@ dist/

# direnv
.envrc

# nix build
result
35 changes: 21 additions & 14 deletions .golangci.yml
Original file line number Diff line number Diff line change
@@ -1,22 +1,9 @@
version: "2"
run:
tests: false

issues:
include:
- EXC0001
- EXC0005
- EXC0011
- EXC0012
- EXC0013

max-issues-per-linter: 0
max-same-issues: 0

linters:
enable:
- bodyclose
- exportloopref
- goimports
- gosec
- nilerr
- predeclared
Expand All @@ -27,3 +14,23 @@ linters:
- unconvert
- unparam
- whitespace
exclusions:
generated: lax
presets:
- common-false-positives
paths:
- third_party$
- builtin$
- examples$
issues:
max-issues-per-linter: 0
max-same-issues: 0
formatters:
enable:
- goimports
exclusions:
generated: lax
paths:
- third_party$
- builtin$
- examples$
158 changes: 154 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
[![Build Status](https://img.shields.io/github/actions/workflow/status/muesli/deckmaster/build.yml?branch=master&style=for-the-badge)](https://github.com/muesli/deckmaster/actions)
[![Go ReportCard](https://goreportcard.com/badge/github.com/muesli/deckmaster?style=for-the-badge)](https://goreportcard.com/report/muesli/deckmaster)

An application to control your Elgato Stream Deck on Linux
An application to control your Elgato Stream Deck on Linux and macOS

## Features

Expand All @@ -18,10 +18,12 @@ An application to control your Elgato Stream Deck on Linux
- Comes with a collection of widgets:
- Buttons
- Time (with formatting)
- CPU/Mem usage
- CPU/Mem/GPU usage
- Temperature sensors
- Weather
- Command output
- Recently used windows (X11-only)
- Several widgets on one key, switched with a tap
- Lets you trigger several actions:
- Run commands
- Emulate a key-press
Expand All @@ -36,6 +38,16 @@ An application to control your Elgato Stream Deck on Linux
- [Packages](https://github.com/muesli/deckmaster/releases) in Alpine, Debian & RPM formats
- [Binaries](https://github.com/muesli/deckmaster/releases) for various architectures

### Nix

This repository is a flake for x86_64-linux, aarch64-linux and aarch64-darwin:

nix run github:psoldunov/deckmaster -- -deck path/to/main.deck

`packages.<system>.default` is the package, and `overlays.default` replaces
`pkgs.deckmaster` with it. `nix develop` opens a shell with Go, gopls and
golangci-lint.

### From source

Make sure you have a working Go environment (Go 1.17 or higher is required).
Expand All @@ -47,6 +59,11 @@ To install deckmaster, simply run:
cd deckmaster
go build

deckmaster draws its text in Roboto. On macOS it only looks for the font in
`~/Library/Fonts`, `/Library/Fonts` and `/System/Library/Fonts`, so install
Roboto there before running a binary built with `go build`. The Nix package
points the binary at Roboto in the Nix store instead.

## System Setup

On Linux you need to set up some `udev` rules to be able to access the device as
Expand Down Expand Up @@ -108,6 +125,39 @@ systemctl --user enable streamdeck.path
systemctl --user start streamdeck.path
```

### macOS

macOS needs no device rules. Quit Elgato's Stream Deck app first, since the two
can't drive the deck at the same time.

`keycode` and `paste` actions post keyboard events, which macOS drops until
deckmaster is allowed in System Settings → Privacy & Security → Accessibility.
deckmaster logs a warning at startup while that permission is missing, and
another line for every key it can't post. The permission belongs to the
process macOS holds responsible: the terminal app when you start deckmaster
from a terminal, and the deckmaster binary itself when a launchd agent starts
it.

macOS ties the grant to that exact binary, so every rebuild loses it, and a
Nix rebuild also moves the binary to a new store path. After each rebuild,
remove the old entry from the Accessibility list and add the new binary, whose
path `readlink -f "$(command -v deckmaster)"` prints.

A few things work differently on macOS:

- `keycode` takes the same key names and numbers as on Linux, translated to
Mac keys. `Leftmeta` and `Rightmeta` are Command, `Leftalt` and
`Rightalt` are Option, `Insert` is Help, and Print Screen, Scroll Lock and
Pause are F13 to F15, the way macOS maps a PC keyboard. `Playpause`,
`Nextsong`, `Previoussong`, `Volumeup`, `Volumedown`, `Mute` and the other
media keys act like the keys on an Apple keyboard. A key with no Mac
equivalent, such as 248 (`KEY_MICMUTE`), is logged and skipped.
- `paste` presses Command-V instead of Ctrl-V.
- `dbus` actions log that they aren't supported.
- The `recentWindow` widget stays empty, since there is no X11.
- The `gpu` and `vram` modes of the `top` widget and the `temp` widget read
Linux's sysfs, so on a Mac they draw an empty bar with a dash.

## Usage

Start `deckmaster` with the initial deck configuration you want to load:
Expand Down Expand Up @@ -174,6 +224,7 @@ A simple button that can display an image and/or a label.
id = "button"
[keys.widget.config]
icon = "/some/image.png" # optional
iconCommand = "~/bin/player-icon" # optional
label = "My Button" # optional
fontsize = 10.0 # optional
color = "#fefefe" # optional
Expand All @@ -182,6 +233,12 @@ A simple button that can display an image and/or a label.

If `flatten` is `true` all opaque pixels of the icon will have the color `color`.

`iconCommand` is a shell command that deckmaster runs on every update of the
widget, once a second unless the widget sets its own `interval`. The command
prints the path of the image to show, either absolute or relative to the deck
file. `icon` is shown until the command first answers. When the command fails
or prints a path that can't be loaded, the key keeps its current icon.

#### Recent Window (requires X11)

Displays the icon of a recently used window/application. Pressing the button
Expand Down Expand Up @@ -235,7 +292,7 @@ Values for `format` are:

#### Top

This widget shows the current CPU or memory utilization as a bar graph.
This widget shows the current CPU, memory or GPU utilization as a bar graph.

```toml
[keys.widget]
Expand All @@ -246,7 +303,63 @@ This widget shows the current CPU or memory utilization as a bar graph.
fillColor = "#d497de" # optional
```

There are two values for `mode`: `cpu` and `memory`.
There are four values for `mode`:

| mode | shows |
| -------- | -------------------------------------- |
| `cpu` | CPU usage |
| `memory` | memory usage |
| `gpu` | how busy the GPU is |
| `vram` | how much of the GPU's memory is in use |

`gpu` and `vram` read the amdgpu card with the most VRAM from
`/sys/class/drm`, so they need Linux and an AMD GPU. When an integrated GPU
sits beside a discrete one, that picks the discrete card. Without an amdgpu
card the bar is drawn empty.

`mode` can hold several modes split on `;`, which share the key as columns
side by side. `fillColor` splits the same way, one color per column in the same
order, and a column without a color of its own gets the default fill:

```toml
[keys.widget]
id = "top"
[keys.widget.config]
mode = "gpu;vram"
fillColor = "#d497de;#9bb6de" # optional
```

#### Temp

This widget shows one hwmon temperature sensor in the same bar as `top`. The
bar fills towards the sensor's critical temperature.

```toml
[keys.widget]
id = "temp"
[keys.widget.config]
chip = "k10temp"
sensor = "Tctl" # optional
device = "nvme0" # optional
label = "CPU" # optional
warn = 80 # optional
crit = 95 # optional
color = "#fefefe" # optional
fillColor = "#d497de" # optional
```

`chip` is the `name` of a chip in `/sys/class/hwmon`, and `sensor` is the
`temp*_label` of a sensor on it. Leave `sensor` out to pick a chip's unlabelled
sensor. When two chips share a name, as two NVMe drives do, `device` picks the
one whose resolved sysfs device path contains it. `label` is drawn under the
bar and defaults to `sensor`.

`warn` and `crit` are in °C. Without them the widget uses the sensor's own
`temp*_max` and `temp*_crit`, and a sensor without a critical temperature fills
the bar at 100 °C. The bar turns orange at the warning temperature and red at
the critical one. A sensor that can't be read shows a dash and is looked up
again on the next update, once a second unless the widget sets its own
`interval`.

#### Command

Expand Down Expand Up @@ -284,6 +397,29 @@ corresponding icons with correct names need to be placed in
`~/.local/share/deckmaster/themes/[theme]`. The default icons with their
respective names can be found [here](https://github.com/muesli/deckmaster/tree/master/assets/weather).

#### Toggle

A widget that holds several widgets on one key and shows one at a time. A tap
switches to the next one.

```toml
[keys.widget]
id = "toggle"
[[keys.widget.config.widgets]]
id = "clock"
[[keys.widget.config.widgets]]
id = "top"
interval = 1000 # optional
[keys.widget.config.widgets.config]
mode = "cpu;memory"
```

Each entry in `widgets` takes the same `id`, `interval` and `config` as a key's
own `widget` table, and a toggle needs at least two. Every entry is built when
the deck loads, so switching back keeps what a widget has already fetched. A
tap switches only on a key without an `action` of its own, and holding the key
doesn't switch.

### Actions

You can hook up any key with several actions. A regular keypress will trigger
Expand Down Expand Up @@ -320,6 +456,20 @@ Emulate a series of key-presses with delay in between:

A list of available `keycodes` can be found here: [keycodes](https://github.com/muesli/deckmaster/blob/master/keycodes.go)

#### Repeat while held

Any action can repeat while its key is held:

```toml
[keys.action]
keycode = "Volumeup"
repeat = 100
```

Once the key is held past a long press (350 ms), the action fires every
`repeat` milliseconds until the key is released. A repeating key never fires
its `keys.action_hold`. A short tap still fires the action once.

#### Paste to clipboard

```toml
Expand Down
2 changes: 2 additions & 0 deletions config.go
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ type ActionConfig struct {
Paste string `toml:"paste,omitempty"`
Device string `toml:"device,omitempty"`
DBus DBusConfig `toml:"dbus,omitempty"`
// Repeat, in milliseconds, re-triggers the action while its key is held.
Repeat uint `toml:"repeat,omitempty"`
}

// WidgetConfig describes configuration data for widgets.
Expand Down
Loading