Stream Deck Kit is a Swift Library for controlling physical Elgato Stream Deck devices with an iPadOS app.
The Stream Deck for iPad SDK is tailored for a seamless plug-and-play experience on iPadOS. Here, your application takes control when it comes to the foreground, dictating the appearance and functions of the Stream Deck's buttons, and for the Stream Deck +, managing its rotary knobs and touchscreen interactions.
All Stream Deck devices:
- Handle key up/down events
Devices with LED keys:
- Set images onto keys
- Set background images
- Render keys and backgrounds with SwiftUI
Devices with Rotary encoders:
- Handle rotation and up/down events
Devices with touch displays:
- Draw onto touch display
- Render touch display content with SwiftUI
To interact with a physical Stream Deck device, ensure you have the following:
- An iPad with a USB-C jack and Apple silicon chip (at least M1)
- The Elgato Stream Deck Connect app installed
- The Stream Deck Device Driver enabled in iOS settings app (Refer to the in-app instructions for guidance)
However, if you want to verify your implementation using the Stream Deck Simulator only, no additional prerequisites are necessary.
iOS Version | Swift Version | XCode Version |
---|---|---|
>= 16 | >= 5.9 | >= 15 |
You can add the library to your XCode project via Swift Package Manager. See "Adding package dependencies to your app".
If you want to add it to your own libraries Package.swift
, use this code instead:
dependencies: [
.package(url: "https://github.com/elgatosf/streamdeck-kit-ipad.git", upToNextMajor: "1.1.0")
]
In order to connect to the Stream Deck driver, you need to add the "Communicates with Drivers" (com.apple.developer.driverkit.communicates-with-drivers
) capability to your app target. Refer to "Adding capabilities to your app" for guidance.
Rendering content on a Stream Deck is very simple with SwiftUI, much like designing a typical app UI.
import StreamDeckKit
StreamDeckSession.setUp(newDeviceHandler: { $0.render(Color.blue) })
This code snippet demonstrates rendering a blue color across all buttons and displays on a device.
Note
StreamDeckSession
operates as a singleton, meaning you should invoke setUp
only once throughout your application's life cycle.
To render content on specific areas, utilize the StreamDeckLayout
system. StreamDeckLayout
provides predefined layout views to position content on a Stream Deck.
import StreamDeckKit
StreamDeckSession.setUp(newDeviceHandler: { $0.render(MyFirstStreamDeckLayout()) })
import SwiftUI
import StreamDeckKit
struct MyFirstStreamDeckLayout: View {
@Environment(\.streamDeckViewContext.device) var streamDeck
var body: some View {
StreamDeckLayout {
// Define key area
// Use StreamDeckKeyAreaLayout for rendering separate keys
StreamDeckKeyAreaLayout { keyIndex in
// Define content for each key.
// StreamDeckKeyAreaLayout provides an index for each available key,
// and StreamDeckKeyView provides a callback for the key action
// Example:
StreamDeckKeyView { pressed in
print("pressed \(pressed) at index \(keyIndex)")
} content: {
Text("\(keyIndex)")
.frame(maxWidth: .infinity, maxHeight: .infinity)
.background(.teal)
}
}.background(.purple)
} windowArea: {
// Define window area
if streamDeck.info.product == .plus {
// Use StreamDeckDialAreaLayout for Stream Deck +
StreamDeckDialAreaLayout { dialIndex in
// Define content for each dial
// StreamDeckDialAreaLayout provides an index for each available dial,
// and StreamDeckDialView provides callbacks for the dial actions
// Example:
StreamDeckDialView { rotations in
print("dial rotated \(rotations)")
} press: { pressed in
print("pressed \(pressed)")
} touch: { location in
print("touched at \(location)")
} content: {
Text("\(dialIndex)")
.frame(maxWidth: .infinity, maxHeight: .infinity)
.background(Color(white: Double(dialIndex) / 5 + 0.5))
}
}
} else if streamDeck.info.product == .neo {
// Use StreamDeckNeoPanelLayout for Stream Deck Neo
StreamDeckNeoPanelLayout { touched in
print("left key touched \(touched)")
} rightTouch: { touched in
print("right key touched \(touched)")
} panel: {
Text("Info Panel")
}
.background(.yellow)
}
}.background(.indigo)
}
}
For instructions on how to react to state changes, refer to Handling state changes.
The SDK is equipped with a fully operational simulator, providing a convenient way to to verify your implementation on various devices. However, we recommend to conduct testing on a real device as well.
Note
The simulator attaches to your running StreamDeckSession
, mimicking the behavior of a regular device.
Executing this code presents the Stream Deck Simulator as an overlay featuring a simulated Stream Deck:
import StreamDeckSimulator
Button("Show Stream Deck Simulator") {
StreamDeckSimulator.show()
}
For further instructions, refer to Simulator.
You can use Simulator in XCode Previews.
#Preview {
StreamDeckSimulator.PreviewView(streamDeck: .mini) { device in
device.render(MyStreamDeckLayout())
}
}
In your app, consider addressing the scenario where Stream Deck Connect, and consequently, its driver, is not installed on the user's device. In such cases, you could prompt users with a message instructing users to install the app and enable the driver before utilizing your app with Stream Deck.
To determine if Stream Deck Connect is installed within your project, use the following snippet with canOpenURL
and its scheme:
UIApplication.shared.canOpenURL(URL(string: "elgato-device-driver://")!)
Ensure to include "elgato-device-driver"
in the LSApplicationQueriesSchemes
section of your Info.plist file.
This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to project owners.
Stream Deck Kit is released under the MIT license. See LICENSE for details.