Stream Deck
Control WolfWave from an Elgato Stream Deck. Play, pause, skip, clear the song-request queue and shared playlist, announce the song, and toggle your overlay.
TL;DR: The WolfWave Stream Deck plugin puts playback, your song-request queue, and your overlay on physical keys. Keys show live state, like what's playing and how many requests are waiting. This page is for streamers. Building your own controller? See the Stream Deck Control API.
The plugin isn't on the Elgato Marketplace yet. For now you install it from the WolfWave repo.
The keys
| Key | What it does |
|---|---|
| Play / Pause | Plays or pauses Apple Music. |
| Skip | Skips to the next track. |
| Hold Queue | Holds or resumes the request queue. Shows the queue size as a big number. |
| Approve Next | Approves the first request waiting for review. Turns amber with the count when requests are waiting. |
| Clear Queue | Clears queued, pending, and playing requests plus the WolfWave Requests playlist. Stops Music when requests exist. Shows the queue size. Hold to fire. Songs stay in your library. |
| Block Song | Adds the current song to your blocklist. |
| Overlay | Shows or hides your stream overlay. |
| Announce Song | Posts what's playing to Twitch chat, same wording as !song. |
| Reject Request | Drops the request that's playing and tells chat, so the requester isn't left guessing. (Skip says nothing.) |
| Block Requester | Stops the person who requested the current song from requesting again. Hold to fire. |
| Request Access | Cycles who may request: Everyone → Subscribers → VIPs & Subs → Mods → Everyone. Shows the current setting. |
| Now Playing | Shows the track and artist scrolling over the album art. Display only: pressing it does nothing. |
How to read them:
- Solid blue means on: playing, queue held, overlay showing.
- Red keys throw something away: Clear Queue and Block Song.
- Counting keys draw their own number. Hold Queue, Approve Next, and Clear Queue leave the key title free, so your own label stays.
Hold-to-fire keys
Clear Queue and Block Requester only fire if you hold them for about a second.
- A quick tap does nothing and flashes an alert.
- Why: one deletes every request with no undo. The other shuts a viewer out. A Stream Deck is a grid of look-alike keys under your hand mid-stream.
Key rules
- Block Requester targets whoever requested the song that's playing, not whoever spoke last.
- To unblock someone, open Settings → Song Requests → Blocklist. It holds people as well as songs and artists.
- Announce Song needs Twitch connected.
- Reject Request and Block Requester need a request to be playing. Otherwise they flash an alert.
- Approve Next only matters if Require My Approval is on in Settings → Song Requests → Who Can Request. See Song Requests.
Install the plugin
You need Bun and a copy of the WolfWave repo.
-
In the repo, run:
bun run --filter streamdeck pack -
Double-click
apps/streamdeck/dist/com.mrdemonwolf.wolfwave.streamDeckPlugin. -
The Stream Deck app installs it and asks you to confirm.
Working on the plugin itself? Run bun run --filter streamdeck build, copy (or symlink) apps/streamdeck/com.mrdemonwolf.wolfwave.sdPlugin into ~/Library/Application Support/com.elgato.StreamDeck/Plugins/, then restart the Stream Deck app.
Connect it to WolfWave
You do this once. Every WolfWave key shares the same connection.
- In WolfWave, open Settings → Stream Widgets and make sure the server is on. Stream Deck and your overlay share it.
- Open Settings → Stream Deck.
- Check Allow Stream Deck commands is on. It's on by default.
- Reveal and copy the Stream Deck Control Token.
- In the Stream Deck app, drag any WolfWave key onto a page and open its settings.
- Paste the token into Control token.
- Leave Port alone unless you changed the WebSocket port in WolfWave. The default is
8765.
Good to know:
- Treat the token like a password. Anything holding it can drive WolfWave from this Mac.
- The overlay token won't work here. It's read-only and can't run commands.
- Streamer Mode blocks copying the token. Turn Streamer Mode off for a moment, copy it, then turn it back on.
- Want the overlay on air but no key presses? Turn off Allow Stream Deck commands. WolfWave then refuses every key press and leaves your overlay running.
- Coming from protocol v1? Copy the new control token once after updating. The old shared token is now the read-only overlay token.
The plugin talks only to WolfWave on this Mac. No outside service is involved, no key press goes over the internet, and the plugin can't be pointed at another Mac.
What the keys tell you
| Key shows | What it means | Fix |
|---|---|---|
| Offline | WolfWave isn't running, Stream Widgets is off, or WolfWave rejected the token (the settings panel says "WolfWave rejected this token"). | Start WolfWave, turn on Stream Widgets, or re-copy the Stream Deck Control Token. The plugin keeps retrying. |
| Token? | The token is missing, or isn't exactly 64 hex characters (0–9, a–f, any case). | Re-copy the Stream Deck Control Token from Settings → Stream Deck. |
| Update | WolfWave and the plugin speak different protocol versions (WolfWave 2.2.0 uses v3). Either side can be older. | Update both so they match. |
- A checkmark flash means the press worked.
- An alert flash means it didn't, for example Approve Next with nothing waiting.
- Every press flashes an alert? Check Allow Stream Deck commands is on in Settings → Stream Deck.
Removed in 2.2.0
Four keys are gone:
- Discord Presence, Music Sync, and Cycle Theme: each flipped a setting you set once. Change them in Settings instead.
- Status: replaced by Now Playing.
Update the plugin and WolfWave together. A mismatch shows Update on every key.
Listening History & Stats
Keep an opt-in, on-device log of what you play in Apple Music, with top artists, listening time, a 7-day trend, a Monthly Wrap, and a !stats chat command.
Streamer Mode
Streamer Mode hides your Twitch channel, overlay links, and tokens in WolfWave so the app is safe on camera. Your overlay, Discord, and chat keep working.