DOCSEARCHbyAlgolia
Submit Docs

Stream Deck SDK

website·Indexed 43 days ago

https://docs.elgato.com

Developer documentation for building Stream Deck plugins using version 1.4.0. Includes guides on creating actions, profiles, and touch strip layouts, as well as technical references for the WebSocket API, manifest JSON Schema, and TypeScript declarations. Covers plugin distribution, app monitoring, localization, and integration with Stream Deck devices.

Tokens
107.8K
Snippets
469
Records
799
Agent score
65%

What's inside Stream Deck SDK

  1. Overview of Supers for OBS Studio

    Supers for OBS Studio allow streamers to dynamically modify, add, remove, and control on-screen elements such as lower thirds, pop-ups, callouts, and calls to action during live streams. The system leverages Lottie animations created in After Effects to provide high customizability. Key capabilities include:

    • Direct configuration of colors, text, and image/icon settings within OBS Studio.
    • Use of shape layers, customizable text, and placeholders for images and videos to create dynamic animations.
    • Seamless integration with the OBS Studio environment to enhance viewer engagement.

  2. Overview of Stream Deck SDK Settings

    The Stream Deck SDK allows plugins to manage persisted settings as JSON objects (supporting booleans, numbers, strings, nulls, arrays, or objects). There are two types of settings:

    1. Action Settings: Associated with a specific instance of a plugin action. Useful for action-specific context or state (e.g., a counter).
    2. Global Settings: Plugin-wide settings. These are stored securely on the user's local machine and should be used for security-sensitive data like API keys or OAuth2 tokens.

    Settings can be managed from the application layer or the Property Inspector (UI). Updates in one layer notify the other automatically.

  3. Overview of Instant Replays for OBS Studio

    Instant Replays for OBS Studio allow streamers to capture and replay key moments during live broadcasts to enhance viewer engagement. The system utilizes After Effects and Lottie animations to create customizable replay sequences. Key capabilities include:

    • Real-time replay integration with OBS Studio.
    • Use of Lottie animations for high customizability.
    • Dynamic design options using shape layers, customizable text, and placeholders for images/videos.
    • Direct configuration of colors, text, and video settings within OBS for real-time adjustments during a stream.

  4. Understand the structure and purpose of One Click Setup files

    A 'One Click Setup' is an HTML document provided by creators (Makers) to allow customers to install comprehensive alert configurations with minimal manual effort. These files encapsulate the design, animations, and interactivity of a custom alert, ensuring the end-user experience matches the designer's original vision. They are compatible with popular streaming platforms including StreamElements and Streamlabs.
    <!-- A One Click Setup file typically contains: -->
<!-- 1. Custom HTML for structure -->
<!-- 2. CSS for styling and animations -->
<!-- 3. JavaScript for interactivity -->

  5. Understand the Stream Deck Encoder concept

    v1
    An 'Encoder' is the collective term for a dial and its corresponding portion of the touch strip on a Stream Deck +. This combination allows plugins to receive dial and touch events and provide visual feedback via layouts on the touch strip.

  6. Manage Action Settings in Stream Deck plugins

    v1

    Action settings are associated with a specific instance of a plugin action. They are useful for providing context to an action (e.g., a counter state) or allowing user customization.

    Key Characteristics:

    • Persisted as JSON objects (supports boolean, number, string, null, arrays, or objects).
    • Stored as plain-text and included in Stream Deck profile exports.
    • Security Warning: Never store security-sensitive data (like API keys) in action settings as they are not secure.

  7. Use the Stream Deck Simulator for iPadOS development

    The Stream Deck Simulator allows developers to test Stream Deck implementations within the Apple iPadOS Simulator, SwiftUI Previews, or directly on an iPad without requiring physical hardware. It replicates hardware behavior by triggering key-down and key-up events via touch interactions. For Stream Deck +, it also simulates dial-presses, dial rotation, and dial area touches. The simulator uses the same image rendering mechanism as the hardware to provide an exact preview of the device display.

  8. Use MediaViewer to display and transform media

    The MediaViewer utility displays images and videos selected via a media-selector property, handling zoom, pan, and rotation as configured in the iCUE media editor. It supports a wide range of image formats (jpg, jpeg, png, gif, bmp, webp, svg, ico) and video formats (mp4, webm, ogg, mov, avi, mkv).

    File dependencies: tools/media_viewer/MediaViewer.js and tools/media_viewer/MediaViewer.css.

  9. Handle DidReceiveResources event

    The didReceiveResources event occurs when resources associated with an action instance are requested or updated. This event provides details about the action's controller type (Keypad, Encoder, or Neo) and its location on the device.
    type DidReceiveResources = {
    action: string;
    context: string;
    device: string;
    event: "didReceiveResources";
    id?: string;
    payload:
        | { // MultiActionPayload
              controller: "Keypad";
              isInMultiAction: true;
              resources: { [key: string]: string; };
              settings: JsonObject;
              state?: number;
          }
        | { // SingleActionPayload
              controller: "Keypad" | "Encoder" | "Neo";
              coordinates: { column: number; row: number; };
              isInMultiAction: false;
              resources: { [key: string]: string; };
              settings: JsonObject;
              state?: number;
          };
};

  10. Understand Stream Deck action types and controllers

    v1

    Stream Deck actions are the core functionality of a plugin and are associated with physical interactive elements called 'controllers'. There are two primary action types:

    • Key: Includes standard buttons, pedals, and G-Keys.
    • Dial: Includes the dial and the associated portion of the touchscreen (found on Stream Deck +).

    Plugins specify which controllers an action supports within the action's metadata in the manifest.

  11. Handle KeyDown events for Stream Deck buttons

    The keyDown event is triggered when a user presses a button on a Stream Deck device. It provides details about the specific action (via UUID), the instance context, and the device. The payload differs based on whether the action is part of a Multi-Action or a Single Action. For buttons, the controller is always Keypad. For dial or touchscreen interactions, use DialDown instead.
    type KeyDown = {
    action: string; // UUID from manifest.json
    context: string; // Unique instance identifier
    device: string; // Device identifier
    event: "keyDown";
    payload:
        | {
              controller: "Keypad";
              isInMultiAction: true;
              resources: { [key: string]: string };
              settings: JsonObject;
              state?: number;
              userDesiredState: number;
          }
        | {
              controller: "Keypad";
              coordinates: { column: number; row: number };
              isInMultiAction: false;
              resources: { [key: string]: string };
              settings: JsonObject;
              state?: number;
          };
};

  12. Understand the Stream Deck plugin architecture

    Stream Deck plugins follow a client-server architecture similar to a web app, but are hosted entirely on the user's local machine. The architecture consists of two primary layers:

    1. Application-layer (Backend): Runs on Node.js. This is the main logic of the plugin, responsible for handling events from the Stream Deck (e.g., key presses).
    2. Presentation-layer (Frontend): Runs in Chromium with DOM access. This is used for the Property Inspector, allowing users to configure actions via HTML views rendered within the Stream Deck app.

    Security Warning: Because plugins run locally on the user's machine, you should never include secrets (such as private API keys) directly in the packaged and distributed plugin code.