Features

WolfWave is packed with features to connect your Apple Music with your streaming audience.

Music Integration

Real-time Now Playing

• ScriptingBridge Integration: Direct communication with Apple Music without spawning subprocesses
• Instant Updates: Track changes are detected and broadcast immediately
• Complete Track Info: Artist, song title, album, and artwork
• Last Played Tracking: Keep history of your recently played songs

Music Monitor Controls

• Toggle tracking on/off from Settings
• Live now-playing preview card in the Music Monitor settings (styled after Apple Music)
• Lightweight background monitoring
• No impact on Apple Music performance

Twitch Integration

Modern API Implementation

• EventSub WebSocket: Real-time chat message notifications using Twitch's modern API
• Helix API: Full integration with Twitch's current API (no deprecated IRC)
• OAuth Device Code Flow: Secure authentication without entering credentials in the app

Chat Commands

Built-in commands for your viewers:

Bot Features

• Command Toggles: Enable/disable individual commands from settings
• Extensible System: Easy to add custom commands
• Reply Support: Commands can reply to specific messages
• Automatic Reconnection: Handles connection drops gracefully

Discord Rich Presence

Listening Status

Show what you're listening to directly on your Discord profile — just like Spotify, but for Apple Music.

• "Listening to Apple Music": Activity type 2 displays a listening status on your profile
• Dynamic Album Artwork: Album art is fetched automatically from the iTunes Search API — no manual setup needed
• Track Details: Displays artist, song title, and album name
• Playback Progress: Shows elapsed time and track duration
• Auto-connect: Connects to Discord automatically when the app launches
• Auto-reconnect: Reconnects when Discord restarts or becomes available

How It Works

WolfWave communicates with Discord via the local IPC socket — no bot token or server required. You only need a Discord Application ID from the Discord Developer Portal.

OBS Stream Widget

Browser Source Overlay

Show what you're listening to directly on your stream with a built-in browser source widget for OBS.

• Local WebSocket Server: Runs on your Mac using Network.framework — no external services needed
• Multi-client Support: Multiple OBS scenes or browser tabs can connect simultaneously
• Real-time Updates: Track changes, progress, and playback state broadcast instantly
• Album Art & Blur: Displays album artwork with a blurred background overlay
• Progress Bar: Smooth progress bar with client-side interpolation for 60fps rendering
• Auto-reconnect: Widget reconnects automatically if the server restarts

How It Works

1. Enable the WebSocket server in Settings → OBS Widget
2. Copy the widget URL
3. Add it as a Browser Source in OBS (recommended size: 500 × 120)
4. The widget connects to the WebSocket address shown in your OBS Widget settings and displays your now-playing info

JSON Message Format

The server broadcasts structured JSON messages:

• welcome — Sent on initial connection
• now_playing — Track name, artist, album, duration, elapsed, artwork URL
• progress — Elapsed time updates every second during playback
• playback_state — Play/pause/stop state changes

First-Launch Onboarding

A guided 4-step onboarding wizard walks new users through initial configuration on first launch:

1. Welcome — App overview with feature highlights
2. Twitch Connection — Optional OAuth Device Code flow to link your Twitch account
3. Discord Rich Presence — Optional toggle to enable listening status on Discord
4. OBS Stream Widget — Optional toggle to enable the WebSocket server with widget URL

Security

Keychain Integration

• All credentials stored in macOS Keychain
• No plain-text token storage
• Secure OAuth token management

Code Signing & Notarization

• App is signed with a Developer ID certificate
• Notarized by Apple for Gatekeeper trust
• Hardened Runtime enabled with no exceptions

Token Management

• Automatic token validation on app launch
• Secure token refresh when possible
• Clear re-authentication prompts when needed

User Interface

Menu Bar App

• Lightweight menu bar presence
• Quick access to Settings, About, and Quit
• Minimal and unobtrusive

Settings Interface

• Music Monitor: Control tracking behavior, live now-playing preview
• App Visibility: Configure dock/menu bar appearance
• OBS Widget: Enable the stream overlay WebSocket server
• Twitch Integration: Manage bot connection and commands
• Discord: Enable/disable Rich Presence and view connection status
• Advanced: Software updates, setup wizard, reset settings

About Panel

The About panel includes clickable links to:

• Documentation — Full docs site
• Privacy Policy — Data handling practices
• Terms of Service — Usage terms

Automatic Updates

WolfWave checks for new versions automatically via the GitHub Releases API.

How It Works

• Checks on launch (after a short delay) and every 24 hours
• Compares the latest release tag against your running version
• Detects whether you installed via Homebrew or DMG download
• Shows a macOS notification when a new version is available

Settings Controls

In Settings → Advanced → Software Update:

• View your current version and available updates
• Homebrew users: Copyable brew upgrade wolfwave command
• DMG users: One-click "Download Update" button
• Skip This Version: Dismiss a specific release
• Check automatically: Toggle periodic checking on/off
• Check Now: Manual check on demand

Technical Features

Performance

• Minimal CPU and memory usage
• Non-blocking async operations
• Efficient polling and event handling

Architecture

• Clean separation of concerns (MVVM pattern)
• Comprehensive error handling
• Zero external dependencies — all native Apple frameworks