Streamdeck Manifest

Stream Deck Plugin — Manifest Reference

Prerequisite: Skim streamdeck-general for the file layout context (the manifest lives at <UUID>.sdPlugin/manifest.json). This skill is the exhaustive field-by-field reference.

Purpose

The manifest is the source of truth for everything Stream Deck needs to load, render, and interact with your plugin: actions, icons, OS/Node versions, profiles, monitored apps. Misconfigure it and the plugin silently fails to appear, or fails validation with an unhelpful error.

This skill enumerates every property with its type, whether it's required, and the most common gotchas. Pair it with the JSON schema for in-editor validation.

Quick start — minimum viable manifest

{
  "$schema": "https://schemas.elgato.com/streamdeck/plugins/manifest.json",
  "UUID": "com.yourhandle.hello-world",
  "Name": "Hello World",
  "Version": "1.0.0.0",
  "Author": "Rick Wilson",
  "Description": "Demonstrates the Stream Deck SDK.",
  "Icon": "imgs/plugin/marketplace",
  "CodePath": "bin/plugin.js",
  "SDKVersion": 2,
  "Software": { "MinimumVersion": "6.6" },
  "OS": [
    { "Platform": "windows", "MinimumVersion": "10" },
    { "Platform": "mac",     "MinimumVersion": "12" }
  ],
  "Nodejs": { "Version": "20" },
  "Actions": [
    {
      "UUID": "com.yourhandle.hello-world.greet",
      "Name": "Greet",
      "Tooltip": "Say hello.",
      "Icon": "imgs/actions/greet/icon",
      "Controllers": ["Keypad"],
      "States": [{ "Image": "imgs/actions/greet/key" }]
    }
  ]
}

Always include $schema. Without it your editor can't validate the file and the CLI errors are far less useful.

File-path extension rules — the #1 source of validation errors

Some manifest fields take a path without an extension; others require an extension. Get this wrong and streamdeck validate complains.

For extension-less fields, Stream Deck auto-picks the best image variant from disk: prefers @2x.png on hi-DPI, falls back to .png, .svg, .jpg, .webp in that order. GIFs are not supported.

Top-level Manifest properties

Required

Optional

Software

"Software": { "MinimumVersion": "7.0" }

Rule of thumb:

OS

Array, at most two entries (one per platform).

"OS": [
  { "Platform": "windows", "MinimumVersion": "10" },
  { "Platform": "mac",     "MinimumVersion": "12" }
]

If you support both, list both. Omit a platform to make the plugin unavailable there.

Nodejs

"Nodejs": { "Version": "20", "Debug": "enabled" }

Actions — the meat

Each entry describes one action exposed to the user. See streamdeck-actions for runtime semantics; here we cover only the manifest shape.

{
  "UUID":                 "com.yourhandle.hello-world.greet",     // reverse-DNS, prefixed by plugin UUID
  "Name":                 "Greet",
  "Tooltip":              "Say hello when pressed.",
  "Icon":                 "imgs/actions/greet/icon",              // no extension
  "Controllers":          ["Keypad"],                             // or ["Encoder"] or ["Keypad", "Encoder"]
  "States":               [{ "Image": "imgs/actions/greet/key" }],
  "PropertyInspectorPath":"ui/greet.html",
  "SupportedInMultiActions": true,
  "VisibleInActionsList":   true,
  "DisableAutomaticStates": false,
  "DisableCaching":         false,
  "UserTitleEnabled":       true
}

Action fields

State

{
  "Image":            "imgs/actions/greet/key",       // no extension; required
  "MultiActionImage": "imgs/actions/greet/key-multi", // optional; shown in Multi-Action picker
  "Name":             "On",                           // optional; shown to user in state picker
  "Title":            "",                             // default title text
  "TitleAlignment":   "middle",                       // "top" | "middle" | "bottom"
  "TitleColor":       "#ffffff",
  "FontFamily":       "Arial",
  "FontSize":         12,
  "FontStyle":        "Bold",                         // "Regular" | "Bold" | "Italic" | "Bold Italic" | ""
  "FontUnderline":    false,
  "ShowTitle":        true
}

Only Image is required. Two states = toggle action (e.g. mute/unmute); the SDK alternates between them on each press unless DisableAutomaticStates.

Encoder (dial actions only)

Required when Controllers includes "Encoder". Configures the touch-strip panel for the dial.

"Encoder": {
  "Icon":       "imgs/actions/volume/encoder-icon",   // no extension
  "background": "imgs/actions/volume/encoder-bg",     // touch-strip background
  "StackColor": "#444444",
  "layout":     "$B1",                                // built-in OR "layouts/custom.json"
  "TriggerDescription": {
    "Push":      "Mute",
    "Rotate":    "Adjust volume",
    "Touch":     "Mute",
    "LongTouch": "Reset"
  }
}

Built-in layouts: $A0, $A1, $B1, $B2, $C1, $X1. Custom JSON layouts live at any path with .json — see streamdeck-profiles-localization for the touch-strip layout schema.

Profiles (optional, bundled profiles)

"Profiles": [
  {
    "Name":                       "default-layout",   // no extension; file is default-layout.streamDeckProfile
    "DeviceType":                 7,                  // Stream Deck + — see device type table
    "Readonly":                   false,
    "DontAutoSwitchWhenInstalled":false,
    "AutoInstall":                true
  }
]

Device type integer table

ApplicationsToMonitor

Tells Stream Deck to notify your plugin when listed apps launch/quit. See streamdeck-system-devices for the event-handler side.

"ApplicationsToMonitor": {
  "mac":     ["com.spotify.client"],
  "windows": ["Spotify.exe"]
}

• macOS: bundle identifiers (find via mdls -name kMDItemCFBundleIdentifier /Applications/Foo.app)
• Windows: executable names (find via Task Manager → Details column)

SDKVersion — 2 vs 3 (DRM)

If you intend to publish on the Marketplace and want piracy protection, go SDKVersion: 3. Otherwise 2 is fine.

TypeScript declaration (abbreviated)

type Manifest = {
  $schema?: "https://schemas.elgato.com/streamdeck/plugins/manifest.json";
  UUID: string;
  Name: string;
  Version: string;                       // "MAJOR.MINOR.PATCH.BUILD"
  Author: string;
  Description: string;
  Icon: string;
  CodePath: string;                      // ends in .js
  CodePathMac?: string;
  CodePathWin?: string;
  SDKVersion: 2 | 3;
  Software: { MinimumVersion: "6.4" | "6.5" | "6.6" | "6.7" | "6.8" | "6.9" | "7.0" | "7.1" | "7.2" | "7.3" | "7.4" };
  OS: [
    { Platform: "mac" | "windows"; MinimumVersion: string },
    { Platform: "mac" | "windows"; MinimumVersion: string }?
  ];
  Nodejs?: { Version: "20" | "24"; Debug?: string; GenerateProfilerOutput?: boolean };
  Category?: string;
  CategoryIcon?: string;
  PropertyInspectorPath?: `${string}.htm` | `${string}.html`;
  DefaultWindowSize?: [number, number];
  URL?: string;
  SupportURL?: string;
  ApplicationsToMonitor?: { mac?: string[]; windows?: string[] };
  Profiles?: Array<{
    Name: string;
    DeviceType: 0|1|2|3|4|5|6|7|8|9|10|11|12|13;
    Readonly?: boolean;
    DontAutoSwitchWhenInstalled?: boolean;
    AutoInstall?: boolean;
  }>;
  Actions: Array<Action>;
};

Full schema (with all enums): https://schemas.elgato.com/streamdeck/plugins/manifest.json

Common validation errors and fixes

See Also

• Official manifest reference: https://docs.elgato.com/streamdeck/sdk/references/manifest
• JSON schema: https://schemas.elgato.com/streamdeck/plugins/manifest.json
• Touch-strip layout schema: https://schemas.elgato.com/streamdeck/plugins/layout.json
• Sibling skills: streamdeck-general, streamdeck-actions, streamdeck-profiles-localization, streamdeck-publishing