geekyeggo/sharpdeck

A .NET wrapper for the official Elgato Stream Deck SDK.

SharpDeck

A comprehensive .NET wrapper for creating Stream Deck plugins, using the official Stream Deck SDK documentation. SharpDeck takes the hassle out of communicating with the Stream Deck SDK, and handles action caching and event delegation.

📦 Examples

• Counter - Single action counter plugin.
• Shared Counter - Multiple action plugin with a shared counter and reset.

✏️ Creating a plugin

SharpDeck enables console applications to easily communicate with Stream Deck; run dotnet new console to create a .NET console application, and follow these five steps to create your first Stream Deck plugin.

🔗 1. Program.cs

public static void Main(string[] args)
{
#if DEBUG
    System.Diagnostics.Debugger.Launch(); 
#endif

    // Connect to Stream Deck.
    SharpDeck.StreamDeckPlugin.Run();
}

⚡ 2. Create an action

using SharpDeck;
using SharpDeck.Events.Received; 

[StreamDeckAction("com.geekyeggo.exampleplugin.firstaction")]
public class MyFirstAction : StreamDeckAction
{
    // Methods can be overriden to intercept events received from the Stream Deck.
    protected override Task OnKeyDown(ActionEventArgs<KeyPayload> args) => ...;
    protected override Task OnKeyUp(ActionEventArgs<KeyPayload> args) => ...;
}

📄 3. Create a manifest.json file

For more information about creating a manifest file, please refer to the SDK documentation.

⚙️ 4. Configure .csproj

<!-- Install the plugin after each build - change authorName and pluginName accordingly. -->
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <OutputPath>$(APPDATA)\Elgato\StreamDeck\Plugins\com.{{authorName}}.{{pluginName}}.sdPlugin\</OutputPath>
    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
</PropertyGroup>

<ItemGroup>
    <!-- The manifest file is required by Stream Deck and provides important information. -->
    <None Update="manifest.json">
        <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
</ItemGroup>

<!-- Kill the Stream Deck process before each build; this allows the copy to occur. -->
<Target Name="PreBuild" BeforeTargets="PreBuildEvent" Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <Exec Command="taskkill -f -t -im StreamDeck.exe -fi &quot;status eq running&quot;" />
</Target>

🚧 5. Debug profile

Located at Properties/launchSettings.json; this debug profile will automatically launch StreamDeck.exe when debugging starts.

{
  "profiles": {
    "DebugWin": {
      "commandName": "Executable",
      "executablePath": "c:\\windows\\system32\\cmd.exe",
      "commandLineArgs": "/S /C \"start \"title\" /B \"%ProgramW6432%\\Elgato\\StreamDeck\\StreamDeck exe\" \""
    }
  }
}

🏃 Running

When debugging starts (default F5):

1. The plugin will be built and installed.
2. Stream Deck will then launch.
3. You will be prompted to attach your plugin to a process; this allows for debugging.

When your plugin is ready, consider packaging and distributing it on the Stream Deck store.

📃 License

The MIT License (MIT) Stream Deck is a trademark or registered trademark of Elgato Systems.

sharpdeck's Issues

Update example to demonstrate Property Inspector decorators

The example should be updated to better demonstrate the usage of the Property Inspector decorators being introduced in #5. This should include a sample PI, ideally using the recommended JS from the Elgato SDK github.

Add support for 4.1 endpoints

Missing endpoints from the new v4.1 SDK.

Events Sent

• getSettings
• setGlobalSettings
• getGlobalSettings
• logMessage

Events Received

• didReceiveSettings
• didReceiveGlobalSettings
• propertyInspectorDidAppear
• propertyInspectorDidDisappear

Automatically publish to NuGet on release

When creating a new release in GitHub, the new version should be published automatically to NuGet.org.

Update examples so they hold at least one PropertyInspector entry.

Would be nice if examples included at least one entry into an action's property inspector so we could figure out the rest via elgato's docs.

Using 7.0.0 beta for SD+ support and I can't seem to figure out how to get the property inspector to show some controls.

Add unit tests

With the introduction of better DI coming in 1.0.2, unit tests should be added to ensure everything is running smoothly.

Deadlocking prevention

To better handle deadlocking of async methods, particularly those triggered within the main StreamDeckClient, we should.

• ConfigureAwait(false) on the top level of start.
• Update the event raisers to be async; a QOL improvement for overriding within custom actions.

Update examples to 6.0.0

Pending release

Incorrect Example

Unless I am mistake, the example on the main page that has:
SharpDeck.StreamDeckClient.Run();

ought to be
SharpDeck.StreamDeckPlugin.Run();

Fast short keypresses trigger OnKeyLongPress

When a button is pressed repeatedly and faster than LongKeyPressInterval, the implementation of StreamDeckAction triggers falsely OnKeyLongPress.

The flow is as follows:

1. Button is pressed
2. OnKeyDown() puts the EventArgs on the stack and starts Task.Delay()
3. Button is released
4. OnKeyUp() successfully pops the EventArgs from the stack and thus calls OnKeyPress() (the callback for short keypress).
5. Problem: The Task.Delay() is still active and waiting.
6. Button is pressed again. This has to happen with 500ms after the first time that the button was pressed (or <= LongKeyPressInterval)
7. OnKeyDown() puts the EventArgs on the stack
8. Task.Delay() from the first button press finishes and successfully pops an event from the stack. Unfortunately, this is the event from the second button press and not from the first button press. In consequence, the callback OnKeyLongPresss() is getting called.

I think that TryHandleKeyPress() must also cancel Task.Delay() when it successfully popped an item from the stack.

Action instances contain incorrect settings

Steps to replicate bug:

1. Create a Play Action at location [1,1] (ref: action 1).
2. 1. Assign an audio track.
3. Create a 2nd Play Action at location [1,2] (ref: action 2).
4. 1. Assign a different audio track.
5. Remove action 1.
6. Move action 2 to [1,1] (where action 1 was).
7. Play action 2 - Audio track is incorrect.

SD+ dial press does not work since Stream Deck v6.5

The event "dialPress" was deprecated with Stream Deck v6.1 and removed in v6.5. The new events are "dialDown" and "dialUp".

PR #21 fixes this.

SetStateAsync sometimes does not work

Hi.

Not sure if I am using the plugin wrong here, or this is a bug.

I have a button, when I press it, it calls a service and changes a value.
When this value is changed, the service will send a callback that triggers an event, that then calls SetStateAsync from a method inside the Action.

I have added Trace.WriteLine that writes out the state I want, but sometimes this is not updated on the button.

If I change the value in the application, without pressing the button, I have not seen this fail (yet).

Improve support for settings to `StreamDeckAction`

ActionPayload currently supports loading the settings, however this uses JObject; it is possible to convert the settings using the helper method T GetSettings<T>(), however it may be beneficial if there were settings and methods directly within the action.

Considerations

• Should a new StreamDeckAction<TSettings> be added to provide helpers?
• When should the settings be loaded; each event vs manual?
• When should the settings be saved; INotifyPropertyChanged vs manual?

Action method decorators, for Property Inspector controllers

Similar to HttpPost / HttpGet, it would be nice if it were possible to decorate methods within a controller that intercepted requests from a Property Inspector, and where desired, "returned" a result.

It should be possible to

• Opt of out auto-routing requests from sendToPlugin.
• Specify the event name (two-way)