Stream Deck Profile Generator

Generate custom Stream Deck profiles for any application by importing a CSV of hotkeys / keyboard shortcuts.

Usage

Create a CSV file with the following columns:

• Hotkey: The keyboard shortcut (e.g. Ctrl C)
• Label: The label to display on the button (e.g. Copy)
• Page: The name of the page to place the button on (e.g. Page One) (optional)
• Id: A unique identifier for the button (e.g. copy) (optional)
• Color: The button color (e.g. red or #FF0000) (optional)

If any of these optional columns are omitted, sensible defaults will be used:

• Page: Pages will be created as needed to fit all buttons (including space for navigation buttons)
• Id: A unique ID will be generated based on the label
• Color: Default button color will be used

Run the generator with your CSV file:

stream-deck-profile-generator --input hotkeys.csv

Or specify any of the available options:

stream-deck-profile-generator \
  --input hotkeys.csv \
  --output MyProfile.streamDeckProfile \
  --profile-name "My Custom Profile" \
  --app-path '/Applications/YourApp.app' \
  --device mk \
  --button-style basic \
  --label-style both \
  --label-position middle \
  --bg-color black \
  --text-color white \
  --font-size 14 \
  --icons-dir ~/path/to/icons

CLI Options

Option	Description	Default
--input <path>	Path to the input CSV file	(required)
--output <path>	Path to the output .streamDeckProfile file	<input-filename>.streamDeckProfile
--profile-name <name>	Name of the profile	<input-filename>
--app-path <path>	Path to the application to switch to for this profile	(optional)
--device <type>	Stream Deck model (e.g. mk, xl, mini)	mk
--button-style <style>	Button style (e.g. basic, border, rainbow, fill)	basic
--label-style <style>	Label style (e.g. label, hotkey, both, none)	both
--label-position <position>	Label vertical position (e.g. top, middle, bottom)	middle
--bg-color <color>	Default button background color (e.g. red, #FF0000)	black
--text-color <color>	Default button text color (e.g. white, #FFFFFF)	white
--font-size <size>	Default button font size	14
--icons-dir <path>	Path to a directory containing SVG, PNG, JPG, GIF or WEBP icons. Matches on the hotkey id	(optional)
--icon-padding <percent>	Padding around icons as a percentage of the button size	10

Button Styles

Button styles are defined in docs/button-styles/:

Preview	Style	Description
	basic	Button with a dark gradient background color
	border	Button with a border around the label
	rainbow	Button with a rainbow border
	fill	Button with a filled background color (defined by --bg-color)

Examples

Some example profiles are available in the examples/ directory.

Chrome Hotkeys (macOS)

• Input: chrome-hotkeys-macos.csv
• Generated Profile: chrome-hotkeys-macos.streamDeckProfile

Basic Button Style

stream-deck-profile-generator --input examples/chrome-hotkeys-macos.csv --profile-name "Chrome Hotkeys (macOS)" --app-path "/Applications/Google Chrome.app"

Border Button Style

stream-deck-profile-generator --input examples/chrome-hotkeys-macos.csv --button-style border

Rainbow Button Style

stream-deck-profile-generator --input examples/chrome-hotkeys-macos.csv --button-style rainbow

Fill Button Style (Custom Colors)

stream-deck-profile-generator --input examples/chrome-hotkeys-macos.csv --bg-color purple --text-color yellow

Chrome Hotkeys (Windows) with Icons

• Input: chrome-hotkeys-windows.csv
• Generated Profile: chrome-hotkeys-windows.streamDeckProfile

This includes an Id column to match against icon filenames in the --icon-path directory.

This example uses Twemoji SVG icons from boywithkeyboard-archive/twemoji_svg:

stream-deck-profile-generator --input examples/chrome-hotkeys-windows.csv --icons-dir ~/path/to/twemoji_svg/files --label-style label

Navigation Buttons

• Input: macos-hotkeys.csv
• Generated Profile: macos-hotkeys.streamDeckProfile

If there are more than 2 pages, Previous/Next navigation buttons will be automatically added to each page in the bottom right corner. This example also demonstrates using a Page column to group buttons onto different pages:

stream-deck-profile-generator --input examples/macos-hotkeys.csv

Customising Individual Buttons

• Input: rainbow-virtual-keyboard.csv
• Generated Profile: rainbow-virtual-keyboard.streamDeckProfile

This includes a Color column to customise individual button colors:

stream-deck-profile-generator --input examples/rainbow-virtual-keyboard.csv --font-size 24 --label-style label

Hotkeys

The parser accepts various formats and aliases. Use either a space or + to separate keys.

Some common supported keys are:

• Meta, Cmd, Command, Windows, Win, ⌘, ⊞
• Control, Ctrl, ^
• Alt, Option, ⌥
• Shift, ⇧
• Enter, Return, ↵
• Escape, Esc, ⎋
• Backspace, ⌫
• Tab, ⇥
• ArrowUp, ArrowDown, ArrowLeft, ArrowRight, ↑, ↓, ←, →
• Space, ␣
• CapsLock, ⇪
• PageUp, PageDown, Home, End, ⇞, ⇟, ⇱, ⇲
• MediaPlayPause, MediaPlayPause, MediaPause, MediaStop, MediaTrackPrevious, MediaTrackNext, ▶, ⏯, ⏸, ⏹, ⏮, ⏭

For example, all of the following are equivalent:

• Meta + C
• Cmd C
• Command C
• ⌘ C - (unicode characters supported)
• Windows C
• Win C
• ⊞ C
• cmd c - (case insensitive)
• Command + C - (using + instead of space)

See Key values for keyboard events on MDN for a list of valid key values and hotkey-aliases.ts for a list of supported aliases.

Development

To install dependencies:

bun install

To run:

bun run generate --input path/to/hotkeys.csv --output MyProfile.streamDeckProfile

To test:

bun test

To run linting and formatting checks (with auto-fixing):

bun fix

To regenerate example profiles:

bun run generate:examples

To generate button style images:

bun run generate:button-styles

Maintainers

• David Taylor