Stop telling chat what song is playing. WolfWave is a tiny native macOS menu bar app that bridges Apple Music with Twitch chat, Discord Rich Presence, and OBS stream overlays. Play something in Apple Music and your Twitch chat, Discord profile, and stream overlay all update on their own.
Free, open source, signed and notarized by Apple. Built for streamers and creators on macOS.
Your music plays. Everything else keeps up.
- Now Playing in Chat. Viewers type
!song,!currentsong, or!nowplayingand instantly see the track you're spinning. - Song Requests. Viewers request songs with
!sr <track>. Requests play through Apple Music without stealing focus from OBS. - Channel Points & Bits. A WolfWave-managed "Request a Song" channel-point reward, plus bit cheers that boost the cheerer's queued track to the front.
- Chat Vote-Skip. Viewers vote off a song with
!voteskipor!vs, in chat-tally mode or native Twitch Polls. - Hold-Mode Queue. Mods hold, resume, skip, and clear the request queue from chat or the menu bar.
- Live Queue View. See what's playing, what's next, and who requested each track right inside the app.
- Fallback Playlist. Configure an Apple Music playlist that takes over when the queue runs dry.
- Approve Before Play. Opt-in "Require My Approval" holds every request (chat, channel points, bits) in the queue until you approve or decline it.
- Fair-Share Ordering. Round-robin queue plays everyone's first request before anyone's second, so a fast re-typist can't hog it. On by default; toggle off for classic FIFO.
- Sub / VIP Priority. Optional perk for subs, VIPs, and mods: skip the request cooldown, or jump ahead within the fair-share round. Off by default.
- Custom Commands. Build your own chat commands with a fixed reply. Variables (
$user,$touser,$args,$1–$9,$song,$lastsong), per-command aliases and cooldowns, and a permission level (Everyone, Subscribers, VIPs, Moderators, or Broadcaster).
- Discord Rich Presence. Shows "Listening to WolfWave" on your Discord profile with Apple Music album art, the active playlist, and clickable open-in-Apple-Music and song.link buttons.
- Stream Widgets. Drop-in browser-source overlay powered by a local WebSocket server with a per-install auth token, five themes (
Default,Dark,Light,Glass,Neon), and five layouts (Horizontal,Vertical,Compact,Vinyl,Classic). Two-PC streamers can connect from a second machine on the LAN. - OBS-friendly by design. Visual progress is batched at 10 Hz, rendering sleeps while hidden or unloaded, and reduced-motion mode removes continuous animation work.
- Listening History & Stats. Opt-in, on-device log of what you actually play: top artists, listening time, 7-day trend, and a listening-by-hour chart built on SwiftUI Charts.
- Monthly Wrap. A personal "wrapped"-style summary for any month, exportable as a shareable PNG.
!statsin Chat. Viewers ask for today's top track. Replies only while you're live.
- macOS 26 Liquid Glass Design. Refreshed onboarding, settings, and menu bar built for Tahoe.
- Light, Dark, or System. Pick an appearance in Settings > General. System follows macOS; Light and Dark override it for the whole app, menu bar included.
- Streamer Mode. One-tap tray toggle that masks your Twitch channel name, widget URLs, and auth token across the UI, so the app is safe to show on camera.
- Backup & Restore. Export your settings to a portable JSON file from Settings > Advanced and bring them back on another Mac or after a reinstall. Accounts and secrets stay in the Keychain, never in the file.
- Song-Change Notifications. Opt-in macOS banner on every track change, with album art. The banner replaces in place instead of stacking.
- Secure by Default. Credentials live in the macOS Keychain, never plain text.
- Automatic Updates. Sparkle for DMG installs, or Homebrew (
brew upgrade --cask). - On-Device Diagnostics. Opt-in MetricKit diagnostics card with a share helper for attaching reports to a bug filing. Reports stay on-device.
- Bug Report Flow. One-click log export and a pre-filled GitHub issue from Advanced settings.
Full docs at mrdemonwolf.github.io/wolfwave.
- Grab the latest
.dmgfrom GitHub Releases. - Open the DMG and drag WolfWave to Applications.
- Launch WolfWave and follow the onboarding wizard.
brew tap mrdemonwolf/den
brew install --cask wolfwaveThe app is signed and notarized by Apple, so there are no Gatekeeper warnings.
| Command | What it does |
|---|---|
!song !currentsong !nowplaying |
Shows the current track |
!lastsong !last !prevsong |
Shows the previous track |
!sr <song> |
Requests a song for the queue |
!queue |
Shows the full request queue |
!myqueue |
Shows just your own requests |
!playlist |
Links the song request playlist |
!voteskip !vs |
Casts a vote to skip the current song |
!stats |
Shows today's top track (live only) |
!wolfwave |
Tells chat what WolfWave is (off by default, four reply styles) |
| Command | What it does |
|---|---|
!skip !next |
Skips the current request |
!hold |
Pauses the queue so you can curate before releasing |
!resume !unhold |
Resumes a held queue |
!clearqueue |
Wipes the queue (with in-app confirmation) |
Streamers can add their own commands (with variables, cooldowns, and a permission level) in Settings > Twitch > Custom Commands, and screen the request queue behind a Require My Approval toggle in Settings > Song Requests > Access.
Enable in Settings > Discord to show what you're listening to on your Discord profile. Album artwork is fetched automatically.
Enable in Settings > Stream Widgets to start the local widget HTTP and WebSocket services. On the same Mac, copy the localhost link; WolfWave injects the WebSocket credential into the served page without exposing it in the URL. For a second computer or phone, use the token-bearing LAN link only on a trusted network.
| Layout | Recommended OBS canvas |
|---|---|
| Horizontal | 532 x 132 |
| Vertical | 252 x 312 |
| Compact | 382 x 88 |
| Vinyl | 292 x 332 |
| Classic | 472 x 144 |
These sizes include the widget's transparent padding. The Stream Deck overlay action hides or shows cards without dropping its authenticated control socket, and regenerating the token disconnects active WebSocket clients.
| Layer | Technology |
|---|---|
| Language | Swift 5.9+ |
| UI | SwiftUI, AppKit |
| Platform | macOS 26.0+ (Tahoe), Apple Silicon, Apple Music app required |
| Music | ScriptingBridge, MusicKit, AppleScript |
| Twitch | EventSub WebSocket, Helix API |
| Discord | Rich Presence via local IPC Unix domain socket |
| Networking | URLSession, Network framework, NWListener (WebSocket overlay) |
| Updates | Sparkle (EdDSA-signed appcast) |
| Charts | SwiftUI Charts (History & Stats) |
| Diagnostics | MetricKit (opt-in) |
| Security | macOS Keychain (Security framework) |
| Docs | Fumadocs (Next.js), bun, Turborepo |
| Marketing | Remotion |
- macOS 26.0+ (Tahoe)
- Apple Silicon (M1 or later)
- Xcode 16.0+
- Swift 5.9+
- bun for docs and marketing workspaces
- Command Line Tools:
xcode-select --install
- Clone the repo:
git clone https://github.com/MrDemonWolf/WolfWave.git
cd WolfWave- Copy the config template:
cp apps/native/WolfWave/Config.xcconfig.example apps/native/WolfWave/Config.xcconfig-
Edit
Config.xcconfigwith your Twitch Client ID and Discord Application ID. Get a Twitch Client ID at dev.twitch.tv/console/apps and a Discord Application ID at discord.com/developers/applications. -
Open the project:
make open-xcodeThen build and run with Cmd+R in Xcode.
Monorepo (bun + Turborepo):
bun installinstalls all workspace dependencies.bun devstarts every dev server via Turbo.bun run dev --filter docsstarts the docs dev server only.bun run build --filter docsbuilds the docs site.bun run dev --filter wolfwave-announcementopens Remotion studio for the launch announcement video.
Native app (Make):
make buildruns a debug build viaxcodebuild.make cleancleans build artifacts.make testruns the unit test suite (runmake testfor the current pass count).make update-depsresolves SwiftPM dependencies.make open-xcodeopens the Xcode project.make ciruns a CI-friendly build.make prod-buildbuilds a release DMG inbuilds/.make prod-installbuilds a release and installs to/Applications.make notarizenotarizes the DMG (requires Developer ID and env vars).make widgetrebuilds the OBS overlay widget (apps/widget/toResources/widget.html). Runbun run tokensfirst when token definitions or their generator changed, or use the ordered rootbun run build.
- Swift 5.9+ with async/await concurrency (no
DispatchQueuefor new async work). - MVVM with
@Observableview models. - MARK sections in every file; DocC-style
///comments on all public APIs. - No force unwrapping. Optionals and
guardonly. - Credentials always via
KeychainService, neverUserDefaults. - Thread-safe service layer (NSLock, serial dispatch queues, MainActor isolation).
- Unit tests auto-discovered via Xcode synchronized groups under
apps/native/WolfWaveTests/.
wolfwave/
├── apps/
│ ├── native/ # Native macOS app (Swift, SwiftUI, AppKit)
│ │ ├── WolfWave/ # App source
│ │ ├── WolfWaveTests/ # Unit tests
│ │ └── WolfWave.xcodeproj # Xcode project
│ ├── docs/ # Fumadocs documentation site
│ ├── marketing/ # Remotion-based promo videos
│ └── widget/ # OBS overlay widget source (builds Resources/widget.html)
├── assets/ # Brand assets, logos
├── design-system/ # Design tokens + component catalog
├── CHANGELOG.md # Release history
├── Makefile # Build, test, release targets
├── package.json # bun workspaces root
└── turbo.json # Turborepo pipeline config
WolfWave is released under the GNU General Public License v3.0 (GPL-3.0).
Questions or feedback?
- Discord: Join my server
- Issues: GitHub Issues
- Docs: mrdemonwolf.github.io/wolfwave
Made with love by MrDemonWolf, Inc.