stream-deck-profile-generator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# Stream Deck Profile Generator
+
+![stream-deck-profile-generator](https://raw.githubusercontent.com/tayles/stream-deck-profile-generator/main/docs/stream-deck-profile-generator-hero.png)
+
+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:
+
+```shell
+stream-deck-profile-generator --input hotkeys.csv
+```
+
+Or specify any of the available options:
+
+```shell
+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/](docs/button-styles/):
+
+| Preview                                                                                                                | Style     | Description                                                     |
+| ---------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------- |
+| ![basic](https://raw.githubusercontent.com/tayles/stream-deck-profile-generator/main/docs/button-styles/basic.png)     | `basic`   | Button with a dark gradient background color                    |
+| ![border](https://raw.githubusercontent.com/tayles/stream-deck-profile-generator/main/docs/button-styles/border.png)   | `border`  | Button with a border around the label                           |
+| ![rainbow](https://raw.githubusercontent.com/tayles/stream-deck-profile-generator/main/docs/button-styles/rainbow.png) | `rainbow` | Button with a rainbow border                                    |
+| ![fill](https://raw.githubusercontent.com/tayles/stream-deck-profile-generator/main/docs/button-styles/filled.png)     | `fill`    | Button with a filled background color (defined by `--bg-color`) |
+
+## Examples
+
+Some example profiles are available in the [examples/](examples/) directory.
+
+### Chrome Hotkeys (macOS)
+
+- Input: [chrome-hotkeys-macos.csv](examples/chrome-hotkeys-macos.csv)
+- Generated Profile: [chrome-hotkeys-macos.streamDeckProfile](examples/chrome-hotkeys-macos.streamDeckProfile)
+
+#### Basic Button Style
+
+![Basic](https://raw.githubusercontent.com/tayles/stream-deck-profile-generator/main/docs/screenshots/chrome-hotkeys-macos-basic-preview.png)
+
+```shell
+stream-deck-profile-generator --input examples/chrome-hotkeys-macos.csv --profile-name "Chrome Hotkeys (macOS)" --app-path "/Applications/Google Chrome.app"
+```
+
+#### Border Button Style
+
+![Border](https://raw.githubusercontent.com/tayles/stream-deck-profile-generator/main/docs/screenshots/chrome-hotkeys-macos-border-preview.png)
+
+```shell
+stream-deck-profile-generator --input examples/chrome-hotkeys-macos.csv --button-style border
+```
+
+#### Rainbow Button Style
+
+![Rainbow](https://raw.githubusercontent.com/tayles/stream-deck-profile-generator/main/docs/screenshots/chrome-hotkeys-macos-rainbow-preview.png)
+
+```shell
+stream-deck-profile-generator --input examples/chrome-hotkeys-macos.csv --button-style rainbow
+```
+
+#### Fill Button Style (Custom Colors)
+
+![Fill](https://raw.githubusercontent.com/tayles/stream-deck-profile-generator/main/docs/screenshots/chrome-hotkeys-macos-fill-preview.png)
+
+```shell
+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](examples/chrome-hotkeys-windows.csv)
+- Generated Profile: [chrome-hotkeys-windows.streamDeckProfile](examples/chrome-hotkeys-windows.streamDeckProfile)
+
+This includes an `Id` column to match against icon filenames in the `--icon-path` directory.
+
+This example uses [Twemoji](https://github.com/twitter/twemoji) SVG icons from [boywithkeyboard-archive/twemoji_svg](https://github.com/boywithkeyboard-archive/twemoji_svg):
+
+![Icons](https://raw.githubusercontent.com/tayles/stream-deck-profile-generator/main/docs/screenshots/chrome-hotkeys-windows-icons-preview.png)
+
+```shell
+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](examples/macos-hotkeys.csv)
+- Generated Profile: [macos-hotkeys.streamDeckProfile](examples/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:
+
+![Navigation](https://raw.githubusercontent.com/tayles/stream-deck-profile-generator/main/docs/screenshots/macos-hotkeys-preview.png)
+
+```shell
+stream-deck-profile-generator --input examples/macos-hotkeys.csv
+```
+
+### Customising Individual Buttons
+
+- Input: [rainbow-virtual-keyboard.csv](examples/rainbow-virtual-keyboard.csv)
+- Generated Profile: [rainbow-virtual-keyboard.streamDeckProfile](examples/rainbow-virtual-keyboard.streamDeckProfile)
+
+This includes a `Color` column to customise individual button colors:
+
+![Fill](https://raw.githubusercontent.com/tayles/stream-deck-profile-generator/main/docs/screenshots/rainbow-virtual-keyboard-preview.png)
+
+```shell
+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](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) for a list of valid key values and [`hotkey-aliases.ts`](src/utils/hotkey-aliases.ts) for a list of supported aliases.
+
+## Development
+
+To install dependencies:
+
+```shell
+bun install
+```
+
+To run:
+
+```shell
+bun run generate --input path/to/hotkeys.csv --output MyProfile.streamDeckProfile
+```
+
+To test:
+
+```shell
+bun test
+```
+
+To run linting and formatting checks (with auto-fixing):
+
+```shell
+bun fix
+```
+
+To regenerate example profiles:
+
+```shell
+bun run generate:examples
+```
+
+To generate button style images:
+
+```shell
+bun run generate:button-styles
+```
+
+## Maintainers
+
+- [David Taylor](https://github.com/tayles)

package/dist/cli.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+import {
+  DEVICES,
+  generateStreamDeckProfile
+} from "./shared/chunk-kjhm4njg.js";
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+
+// src/types/types.ts
+var BUTTON_STYLES = ["basic", "border", "rainbow", "fill"];
+var LABEL_STYLES = ["none", "label", "hotkey", "both"];
+var LABEL_POSITIONS = ["top", "middle", "bottom"];
+
+// src/cli.ts
+var USAGE = `
+Usage: stream-deck-profile-generator [options]
+
+Generate a Stream Deck profile from a CSV file.
+
+Required Options:
+  --input <path>              Path to the input CSV file
+
+Optional:
+  --output <path>             Path to the output .streamDeckProfile file
+                              (defaults to <input-filename>.streamDeckProfile)
+  --profile-name <name>       Name of the profile
+  --app-path <path>           Path to the application to switch to for this profile
+  --device <type>             Stream Deck model: ${Object.keys(DEVICES).join(", ")}
+                              (default: mk)
+  --button-style <style>      Button style: ${BUTTON_STYLES.join(", ")}
+                              (default: basic)
+  --label-style <style>       Label style: ${LABEL_STYLES.join(", ")}
+                              (default: both)
+  --label-position <pos>      Label position: ${LABEL_POSITIONS.join(", ")}
+                              (default: middle)
+  --bg-color <color>          Default button background color
+                              (default: black)
+  --text-color <color>        Default button text color
+                              (default: white)
+  --font-size <size>          Default button font size (1-72)
+                              (default: 14)
+  --icons-dir <path>          Path to directory containing custom icons
+  --icon-padding <percent>    Padding around icons as a percentage of button size
+                              (default: 10)
+  --help, -h                  Show this help message
+
+Examples:
+  stream-deck-profile-generator --input hotkeys.csv
+  stream-deck-profile-generator --input hotkeys.csv --output MyProfile.streamDeckProfile
+  stream-deck-profile-generator --input hotkeys.csv --profile-name 'My Custom Profile' --app-path '/Applications/SomeApp.app'
+  stream-deck-profile-generator --input hotkeys.csv --device xl --button-style rainbow
+  stream-deck-profile-generator --input hotkeys.csv --icons-dir ./icons --bg-color blue
+`;
+async function main() {
+  try {
+    const { values } = parseArgs({
+      args: process.argv.slice(2),
+      options: {
+        input: { type: "string" },
+        output: { type: "string" },
+        "profile-name": { type: "string" },
+        "app-path": { type: "string" },
+        device: { type: "string" },
+        "button-style": { type: "string" },
+        "label-style": { type: "string" },
+        "label-position": { type: "string" },
+        "bg-color": { type: "string" },
+        "text-color": { type: "string" },
+        "font-size": { type: "string" },
+        "icons-dir": { type: "string" },
+        "icon-padding": { type: "string" },
+        help: { type: "boolean", short: "h" }
+      },
+      allowPositionals: false
+    });
+    if (values.help) {
+      console.log(USAGE);
+      process.exit(0);
+    }
+    if (!values.input) {
+      console.error(`❌ Error: --input is required
+`);
+      console.log(USAGE);
+      process.exit(1);
+    }
+    const options = {
+      inputPath: values.input
+    };
+    if (values.output) {
+      options.outputPath = values.output;
+    }
+    if (values["profile-name"]) {
+      options.profileName = values["profile-name"];
+    }
+    if (values["app-path"]) {
+      options.appPath = values["app-path"];
+    }
+    if (values.device) {
+      if (!Object.keys(DEVICES).includes(values.device)) {
+        console.error(`❌ Error: Invalid device ID: ${values.device}`);
+        console.error(`Valid options: ${Object.keys(DEVICES).join(", ")}`);
+        process.exit(1);
+      }
+      options.deviceId = values.device;
+    }
+    if (values["button-style"]) {
+      if (!BUTTON_STYLES.includes(values["button-style"])) {
+        console.error(`❌ Error: Invalid button style: ${values["button-style"]}`);
+        console.error(`Valid options: ${BUTTON_STYLES.join(", ")}`);
+        process.exit(1);
+      }
+      options.buttonStyle = values["button-style"];
+    }
+    if (values["label-style"]) {
+      if (!LABEL_STYLES.includes(values["label-style"])) {
+        console.error(`❌ Error: Invalid label style: ${values["label-style"]}`);
+        console.error(`Valid options: ${LABEL_STYLES.join(", ")}`);
+        process.exit(1);
+      }
+      options.labelStyle = values["label-style"];
+    }
+    if (values["label-position"]) {
+      if (!LABEL_POSITIONS.includes(values["label-position"])) {
+        console.error(`❌ Error: Invalid label position: ${values["label-position"]}`);
+        console.error(`Valid options: ${LABEL_POSITIONS.join(", ")}`);
+        process.exit(1);
+      }
+      options.labelPosition = values["label-position"];
+    }
+    if (values["bg-color"]) {
+      options.bgColor = values["bg-color"];
+    }
+    if (values["text-color"]) {
+      options.textColor = values["text-color"];
+    }
+    if (values["font-size"]) {
+      const fontSize = parseInt(values["font-size"], 10);
+      if (isNaN(fontSize) || fontSize < 1 || fontSize > 72) {
+        console.error("❌ Error: Font size must be a number between 1 and 72");
+        process.exit(1);
+      }
+      options.fontSize = fontSize;
+    }
+    if (values["icons-dir"]) {
+      options.iconsDir = values["icons-dir"];
+    }
+    if (values["icon-padding"]) {
+      const padding = parseInt(values["icon-padding"], 10);
+      if (isNaN(padding) || padding < 0 || padding > 50) {
+        console.error("❌ Error: Icon padding must be a number between 0 and 50");
+        process.exit(1);
+      }
+      options.iconPaddingPercent = padding;
+    }
+    console.log(`\uD83D\uDE80 Generating Stream Deck profile...
+`);
+    await generateStreamDeckProfile(options);
+  } catch (error) {
+    console.error("❌ Error:", error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+await main();

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+declare const DEVICES: {
+	readonly mk: {
+		readonly name: "Stream Deck";
+		readonly model: "20GBA9901";
+		readonly rows: 3;
+		readonly columns: 5;
+	};
+	readonly xl: {
+		readonly name: "Stream Deck XL";
+		readonly model: "20GAT9901";
+		readonly rows: 4;
+		readonly columns: 8;
+	};
+	readonly mini: {
+		readonly name: "Stream Deck Mini";
+		readonly model: "20GAI9901";
+		readonly rows: 2;
+		readonly columns: 3;
+	};
+	readonly plus: {
+		readonly name: "Stream Deck +";
+		readonly model: "20GBD9901";
+		readonly rows: 2;
+		readonly columns: 4;
+	};
+	readonly neo: {
+		readonly name: "Stream Deck Neo";
+		readonly model: "20GBJ9901";
+		readonly rows: 2;
+		readonly columns: 4;
+	};
+	readonly mobile: {
+		readonly name: "Stream Deck Mobile";
+		readonly model: "VSD/WiFi";
+		readonly rows: 3;
+		readonly columns: 5;
+	};
+};
+type DeviceId = keyof typeof DEVICES;
+declare const BUTTON_STYLES: readonly ["basic", "border", "rainbow", "fill"];
+type ButtonStyle = (typeof BUTTON_STYLES)[number];
+declare const LABEL_STYLES: readonly ["none", "label", "hotkey", "both"];
+type LabelStyle = (typeof LABEL_STYLES)[number];
+declare const LABEL_POSITIONS: readonly ["top", "middle", "bottom"];
+type LabelPosition = (typeof LABEL_POSITIONS)[number];
+interface Options {
+	inputPath: string;
+	outputPath?: string;
+	deviceId?: DeviceId;
+	buttonStyle?: ButtonStyle;
+	labelStyle?: LabelStyle;
+	labelPosition?: LabelPosition;
+	bgColor?: string;
+	textColor?: string;
+	fontSize?: number;
+	iconsDir?: string;
+	iconPaddingPercent?: number;
+	profileName?: string;
+	appPath?: string;
+}
+/**
+* Create this file structure in the out/ dir:
+*
+* @example
+* <profile-uuid>.sdProfile/
+* ├── manifest.json
+* └── Profiles/
+*     ├── <pinned-page-folder-id>/
+*     │   ├── manifest.json
+*     │   └── Images/
+*     ├── <page-1-folder-id>/
+*     │   ├── manifest.json
+*     │   └── Images/
+*     │       ├── <hotkey-1-id>.png
+*     │       ├── <hotkey-2-id>.png
+*     │       └── ...
+*     └── <page-2-folder-id>/
+*         ├── manifest.json
+*         └── Images/
+*             ├── <hotkey-5-id>.png
+*             ├── <hotkey-6-id>.png
+*             └── ...
+*/
+declare function generateStreamDeckProfile(options: Options): Promise<void>;
+export { generateStreamDeckProfile };

package/dist/index.js

@@ -0,0 +1,6 @@
+import {
+  generateStreamDeckProfile
+} from "./shared/chunk-kjhm4njg.js";
+export {
+  generateStreamDeckProfile
+};