| title | Capture Stream Deck Reference Profile |
| name | capture-streamdeck-reference |
| description | Build and validate a reference .streamDeckProfile containing all known built-in Stream Deck action types for reverse engineering |
| version | 1.0.0 |
| created | 2026-04-21T00:00:00.000Z |
| lastmod | 2026-04-23T03:05:07.000Z |
Charter
Invoke this skill when asked to build, update, or re-verify the reference profile that documents every known built-in Stream Deck action type. The reference profile serves as a ground-truth JSON corpus for reverse engineering action schemas and validating engine output.
Inputs and Outputs
Inputs:
- Optional: specific action type(s) to add or verify
- Optional: target profile name (default:
reference-all-actions)
Outputs:
- Updated extracted profile at
profiles/reference-all-actions/ (in opendeck-factory)
- Packed
.streamDeckProfile at originals/reference-all-actions.streamDeckProfile (in stream-deck-catalog)
Tool Safety
| Category | Operations |
|---|
| SAFE_READ | node src/index.js list, node src/index.js validate, reading manifest JSON |
| DESTRUCTIVE | Running expand-reference-profile.js, writing manifest files, pack |
| GUI (subagent only) | Right-click gestures (Pin, Wallpaper), Export via Stream Deck app |
Never run DESTRUCTIVE operations against the live %APPDATA%\Elgato\StreamDeck\ProfilesV3\ directory while the Stream Deck app is running — changes write through to app state.
Workflow
Step 1: Verify Current State
Read the page manifests directly to see which action types are present:
ls profiles/reference-all-actions/Profiles/
cat profiles/reference-all-actions/Profiles/<page-uuid>/manifest.json
Compare the Actions keys against the known action type inventory (see Reference section below).
Step 2: Regenerate via Script
The authoritative generator is scripts/expand-reference-profile.js. Run it against the live profile directory:
node scripts/expand-reference-profile.js
This script:
- Writes all 4 page manifests (Navigation, System, Profile, Multi-action)
- Generates composite SVG icons (colored background + plugin icon) for every button
- Uses viewBox-aware wrapping to normalize icons from different plugin coordinate spaces to 144×144
viewBox handling: icons from different plugins use inconsistent SVG coordinate spaces (24px, 72px, 144px). For non-144×144 viewBoxes, the script uses <g transform="scale(N)"> where N = 144/viewBoxWidth. Note: nested <svg viewBox> was tried but the Stream Deck app ignores nested SVG elements — <g transform> is the correct approach.
Step 3: Validate
The validate command does not work on this profile (format mismatch — see Step 1 note). Validation is:
- The script ran without errors
- Visual inspection in the Stream Deck app — navigate all 4 pages and confirm buttons render correctly
Step 4: Pack and Copy to Catalog
node src/index.js pack profiles/reference-all-actions "builds/Reference All Actions.streamDeckProfile"
cp "builds/Reference All Actions.streamDeckProfile" ../stream-deck-catalog/originals/reference-all-actions.streamDeckProfile
Step 5: Add New Action Types (if needed)
To add an action type not yet in the reference profile:
- Identify the action's plugin ID and icon path under
%APPDATA%\Elgato\StreamDeck\plugins\
- Add an entry to the
ICON map in expand-reference-profile.js
- Add a row to the appropriate page's layout array
- If the action requires GUI gestures (Pin, Wallpaper), invoke the
streamdeck-driver subagent to place the action via the app, then export and compare the resulting manifest to learn the schema
- Add the discovered schema to the engine or document it in
docs/obsidian-vault/
Reference: Known Action Types
Page 1 — System (electric blue)
| Col | Row | Action ID | Label |
|---|
| 0 | 0 | com.elgato.streamdeck.system.website | Website |
| 1 | 0 | com.elgato.streamdeck.system.hotkeyswitch | Hotkey Switch |
| 2 | 0 | com.elgato.streamdeck.system.hotkey | Hotkey Ctrl+A |
| 3 | 0 | com.elgato.streamdeck.system.open | Open |
| 4 | 0 | com.elgato.streamdeck.page.indicator (app-rendered) | Page Indicator |
| 0 | 1 | com.elgato.streamdeck.system.close | Close |
| 1 | 1 | com.elgato.streamdeck.system.text | Text |
| 2 | 1 | com.elgato.streamdeck.system.openapp | Open App |
| 3 | 1 | com.elgato.streamdeck.system.multimedia (actionIdx:0) | Prev Track |
| 4 | 1 | com.elgato.streamdeck.system.multimedia (actionIdx:1) | Play/Pause |
| 0 | 2 | com.elgato.streamdeck.page (nav) | ← Prev Page |
| 1 | 2 | com.elgato.streamdeck.system.multimedia (actionIdx:2) | Next Track |
| 2 | 2 | com.elgato.streamdeck.system.multimedia (actionIdx:3) | Stop |
| 3 | 2 | com.elgato.streamdeck.system.multimedia (actionIdx:4) | Mute |
| 4 | 2 | com.elgato.streamdeck.page (nav) | Next Page → |
Page 2 — Stream Deck (vivid orange)
| Col | Row | Action ID | Label |
|---|
| 0 | 0 | com.elgato.streamdeck.system.timer | Timer |
| 1 | 0 | com.elgato.streamdeck.system.keybrightness (actionIdx:0) | Brighter |
| 2 | 0 | com.elgato.streamdeck.system.keybrightness (actionIdx:1) | Darker |
| 3 | 0 | com.elgato.streamdeck.system.keybrightness (actionIdx:2) | Max |
| 4 | 0 | com.elgato.streamdeck.page.indicator (app-rendered) | Page Indicator |
| 0 | 1 | com.elgato.streamdeck.system.keybrightness (actionIdx:4) | Medium |
| 1 | 1 | com.elgato.streamdeck.system.keybrightness (actionIdx:5) | Low |
| 2 | 1 | com.elgato.streamdeck.system.keybrightness (actionIdx:6) | Minimum |
| 3 | 1 | com.elgato.streamdeck.system.sleep | Sleep |
| 4 | 1 | com.elgato.streamdeck.vsdtoggle | Toggle VSD |
| 0 | 2 | com.elgato.streamdeck.page (nav) | ← Prev Page |
| 1 | 2 | com.elgato.streamdeck.system.keybrightness (actionIdx:3) | High |
| 2 | 2 | com.elgato.streamdeck.system.multimedia (actionIdx:6) | Vol- |
| 3 | 2 | com.elgato.streamdeck.system.multimedia (actionIdx:5) | Vol+ |
| 4 | 2 | com.elgato.streamdeck.page (nav) | Next Page → |
Page 3 — Navigation (vivid emerald)
| Col | Row | Action ID | Label |
|---|
| 0 | 0 | com.elgato.streamdeck.profile.rotate | Switch Profile |
| 1 | 0 | com.elgato.streamdeck.page.goto | Go to Page |
| 4 | 0 | com.elgato.streamdeck.page.indicator (app-rendered) | Page Indicator |
| 0 | 1 | com.elgato.streamdeck.profile.backtoparent | Parent Folder |
| 0 | 2 | com.elgato.streamdeck.page (nav) | ← Prev Page |
| 4 | 2 | com.elgato.streamdeck.page (nav) | Next Page → |
| GUI only | — | com.elgato.streamdeck.profile.openchild | Create Folder (see GUI Capture table) |
Page 4 — Soundboard + Multi Act + Keys (vivid violet)
| Col | Row | Action ID | Label |
|---|
| 0 | 0 | com.elgato.streamdeck.soundboard.playaudio | Play Audio |
| 1 | 0 | com.elgato.streamdeck.soundboard.stopaudioplay | Stop Audio |
| 2 | 0 | com.elgato.streamdeck.multiactions.routine | Multi Action |
| 3 | 0 | com.elgato.streamdeck.multiactions.routine2 | Multi Switch |
| 4 | 0 | com.elgato.streamdeck.page.indicator (app-rendered) | Page Indicator |
| 0 | 1 | com.elgato.streamdeck.keys.logic | Key Logic |
| 1 | 1 | com.elgato.streamdeck.multiactions.delay | Delay |
| 2 | 1 | com.elgato.streamdeck.system.digitaltime | Digital Time |
| 3 | 1 | com.elgato.streamdeck.keys.adaptor | Key Adaptor |
| 4 | 1 | com.elgato.streamdeck.keys.stack | Key Stack |
| 0 | 2 | com.elgato.streamdeck.page (nav) | ← Prev Page |
| 1 | 2 | com.elgato.streamdeck.multiactions.random | Random Action |
| 2 | 2 | com.elgato.streamdeck.system.pagination | Pagination |
| 4 | 2 | com.elgato.streamdeck.page (nav) | Next Page → |
Action Types Requiring GUI Capture
These action types cannot be placed via JSON injection alone — their schema is incomplete or they require right-click gestures. Use the drive-windows-gui skill for all of these.
| Action | UUID | Status | Reason | Subagent task |
|---|
| Create Folder | com.elgato.streamdeck.profile.openchild | ❌ Not captured | Requires sub-profile structure the app creates on placement; JSON-only placement is silently dropped | Drag-drop onto Page 3, export manifest, diff against engine-generated |
| Pinned Action | unknown | ❌ Not captured | Right-click → Pin gesture only; no JSON equivalent | Right-click any button → Pin, export, read manifest |
| Wallpaper | unknown | ❌ Not captured | Right-click → Set Wallpaper from file | Right-click canvas → Set Wallpaper, export, read manifest |
| Multi Action title+icon | com.elgato.streamdeck.multiactions.routine | ❌ Not captured | Engine-placed Multi Action renders display incorrectly vs GUI-placed | Place via GUI, export, diff States and Settings vs engine output |
After capturing each schema, document the discovered fields in docs/obsidian-vault/ and add to expand-reference-profile.js where applicable.
Use the streamdeck-driver subagent for these. After capture, diff the exported manifest against an engine-generated one to identify the missing fields.
Plugin Icon Paths
Icons are sourced from installed Stream Deck plugins:
%APPDATA%\Elgato\StreamDeck\plugins\<plugin-id>.sdPlugin\Images\<icon-file>.svg
Key plugin IDs:
com.elgato.streamdeck.profile.sdPlugin — profile navigation iconscom.elgato.streamdeck.multiactions.sdPlugin — multi-action iconscom.elgato.streamdeckweb.sdPlugin — web/URL iconscom.elgato.streamdeck.sdPlugin — core system icons (hotkey, open, text, media)
Troubleshooting
App creates extra pages while Stream Deck is running: Stop the app before writing manifests. Scanning near the "+" button coordinate (x_client≈375) can trigger page creation via SendMessage. If this happens: stop app, remove the spurious UUID from the root package.json Pages array, delete its directory, re-run the generator, restart app.
Page 6 accidentally created: This happened during coordinate scanning (x_client=375, y=380–500 range hit the "+" button). Fix: stop app → remove UUID from root manifest → delete directory → re-run script → restart app.
SVG icons display as blank: Check that the viewBox wrapper is applied. Icons with non-144×144 viewBoxes (e.g., 0 0 20 20, -12 -12 48 48, 0 0 72 72) need the nested <svg viewBox> treatment in writeComposite().
