kobendev / sharpdeck

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

SharpDeck

A comprehensive .NET wrapper for creating Stream Deck plugins, using the official Elgato Stream Deck SDK.

⚡ What does it do?

SharpDeck takes the hassle out of communicating with the Stream Deck SDK, and handles caching and calling your actions! At a glance, SharpDeck handles...

• Connecting to the Stream Deck.
• Registering your custom actions.
• Calling your custom actions when something happens (i.e. button press).

📦 Examples

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

📄 Getting started

We recommend taking a look at the official Stream Deck SDK documentation. Each plugin has a manifest.json file (example) which tells Stream Deck everything about your plugin, and it's actions.

✏️ Writing your plugin

1. Create a .NET console app (Framework or Core supported).
2. Add your manifest.json file.
   • Set the Copy to Output Directory property to Copy Always.
3. Add SharpDeck dotnet add package SharpDeck.
4. Update Program.cs to initiate your plugin.

   public static void Main(string[] args)
   {
   #if DEBUG
       // optional, but recommended
       System.Diagnostics.Debugger.Launch(); 
   #endif
       
       // register actions and connect to the Stream Deck
       SharpDeck.StreamDeckPlugin.Run();
   }

5. Create your action as a class. Each action must,
   • Have the attribute [StreamDeckAction(UUID)], with a unique UUID.
   • Inherit from either StreamDeckAction, or StreamDeckAction{TSettings}.

🚧 Testing your plugin

1. Navigate to %APPDATA%\Elgato\StreamDeck\Plugins, this is where all Stream Deck plugins live.
2. Create a folder for your plugin, typically com.{author}.{plugin}.sdPlugin.
3. Copy your files from your bin\Debug folder to your plugin folder.
4. Restart Stream Deck, and your plugin should be there! 👍

🛠️ Make testing quicker and easier (optional)

Copying your plugin each time can be a bit tedious, but don't worry, there's a few steps to make it easier!

1. Ensure your Program.cs calls System.Diagnostics.Debugger.Launch();.
2. Add a pre-build task to terminate StreamDeck.exe process:
   • taskkill -f -t -im StreamDeck.exe -fi "status eq running"
3. Build to your plugin folder directly:
   • e.g. <OutputPath>$(APPDATA)\Elgato\StreamDeck\Plugins\com.geekyeggo.counter.sdPlugin\</OutputPath>
4. Create a debug profile in Properties/launchSettings.json (example).

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

5. Voila, F5 should now terminate Stream Deck, rebuild your plugin, and then re-launch Stream Deck!

🚨 Need help?

1. If you can't see your plugin at all:
   • Check your plugin folder contains your plugin's executable.
   • Check the manifest.json file exists, and the codePath points to your executable.
2. If you can see your plugin but it isn't working:
   • Check %APPDATA%\Elgato\StreamDeck\logs if there are any logs for your plugin.
   • Update your Program.cs to call Debugger.Launch() (example) which will allow you to debug your plugin.

Still can't get it working? No problems, raise an issue and we'll try to help!

📃 License

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