Skip to content
Integration

Stream Deck (WebHID native) — driver-free setup

Pair an Elgato Stream Deck MK.2 with Timers Studio directly from the browser — no Elgato software, no background service. WebHID handles the device natively. This guide covers the first pairing, the default key map, and how to extend it.

Hardware
Elgato MK.2 (15 keys)
Protocol
WebHID (browser-native)
Software
None required
Companion alternative Browser support

Last updated

Stream Deck (WebHID native) — driver-free setup

Timers Studio talks to an Elgato Stream Deck directly through the browser’s WebHID API. Nothing to install on the operator machine — no Elgato software, no background service, no plugin. The keys light up with SVG icons pushed from the Studio, and every press triggers a controller action (play, pause, next, cue message, flash).

What you need

  • An Elgato Stream Deck MK.2 (15 keys). Other models (Mini, XL, +) are on the roadmap.
  • Chrome, Edge, Brave, Arc, or any Chromium-based browser at version 89 or above. Firefox and Safari do not implement WebHID.
  • A USB-A or USB-C cable plugged straight into the operator’s computer. Powered hubs work. KVM switches sometimes drop the HID handshake — avoid them during the show.

First pairing

  1. Open the Studio at timers.studio/id/<your-room>.
  2. Open the Customize modal (gear icon in the header) and scroll to the Stream Deck section.
  3. Click Pair Stream Deck. The browser shows a native device picker — pick the line that reads Elgato Stream Deck. Once approved, the keys light up with the default icons within a second.
  4. The pairing is remembered per-origin: next time you open the same room on the same browser profile, the device is recognised automatically. If you change browser profile, machine, or clear site data, repeat the pairing.

Default key map (MK.2, 15 keys)

RowKeyAction
11Previous timer
12Play / Pause
13Stop
14Next timer
15Reset current timer
26-1 min
27-30 sec
28+30 sec
29+1 min
210Blackout Player
311Send message slot 1
312Send message slot 2
313Send message slot 3
314Flash TIME UP
315Clear messages

Every key is re-mappable from the Customize modal. Drop any of the 50+ available actions onto any slot.

How the WebHID bridge works

When you click Pair, the Studio requests access to HID devices with the Elgato vendor ID (0x0FD9). Chrome surfaces its own picker — this is a hard security boundary, the Studio never sees devices you did not approve. Once granted, the Studio opens a long-lived HID connection and:

  • Writes framebuffers to each key as WebP-encoded bitmaps (72×72 px on MK.2).
  • Reads input reports on key press / release and dispatches them to the controller bus.
  • Shuts the connection cleanly on tab close. The device reverts to its firmware default within a second.

The code path lives in components/streamdeck/useStreamDeck.ts — it’s a single React hook around the navigator.hid object.

Remote Stream Deck (director on the move)

The Studio exposes a /streamdeck/<room> route that bridges a remote operator machine into the same controller. Pair the deck on a laptop in the back of the room, put the laptop to sleep — the hardware wakes when the runner presses a key from their backstage iPad, because the bridge keeps the controller state synced over Supabase.

Troubleshooting

The keys are blank. The browser never received the WebP frames. Check the devtools console for hid-write errors — usually a power issue. Try a different USB port or remove the hub.

Chrome does not show the device picker. You are on a non-Chromium browser. Open the Studio in Chrome, Edge, Brave, or Arc. WebHID is a Chromium-only spec for now.

Keys fire twice. Two tabs are connected to the same device. Close the spare.

The deck freezes on a black rectangle. The firmware crashed — unplug, wait two seconds, plug back in. Pair again.

See also