How to Use

WolfWave runs itself once set up. Here's how each piece works.

The Menu Bar

WolfWave lives in your macOS Menu Bar (top-right of your screen).

• Click the wolf icon to see what's playing.
• From the menu: quick toggles, hold/resume the request queue, open Settings.

Sync Music

Flip the Sync Music switch in Settings. WolfWave instantly spots when you change a song.

Now-Playing Widget

WolfWave serves the widget HTML and now-playing data from your Mac; no hosted overlay service is involved. Fresh album artwork and online integrations still require internet access.

Auth Token

The WebSocket connection is gated by a per-install token stored in the macOS Keychain. The static HTTP shell itself is not authenticated.

• Reveal it: Eye toggle next to the token field. Hidden by default.
• Regenerate: Drops every active client. Re-copy the Widget Link into OBS afterward.
• Custom value: Edit the token field to supply your own string (handy when you want a memorable value or you're rotating after a leak).

Connecting from a second computer or phone? Use http://<your-lan-ip>:8766/?token=<token>. The browser script consumes the query token and sends it in the authenticated WebSocket subprotocol; use this plaintext local transport only on a trusted LAN.

Themes & Layouts

Pick from five themes (Default, Dark, Light, Glass, Neon) and five layouts (Horizontal, Vertical, Compact, Vinyl, Classic) in Settings → Stream Widgets.

Twitch Chat Bot

Once you're logged into Twitch (Settings → Twitch), the bot auto-connects when you open the app.

• Pick commands: Choose which ones chat can use (like !song, !last, !sr, !voteskip, !stats).
• Cooldowns: Set wait times so nobody spams.
• Mod Bypass: Mods and you can use commands as much as you want.
• Custom commands: Add your own !command with a fixed reply, variables, cooldowns, and a permission level in Settings → Twitch → Custom Commands.

See the Bot Commands page for the full list, including Vote-Skip and Live Stats.

Song Requests

Open Settings → Song Requests and run the quick guided setup. It checks your Twitch connection, asks for Apple Music access, and creates the WolfWave Requests playlist. You can't switch requests on until setup is done, so nothing half-configured ever goes live.

• How chat uses it: !sr <song name, or Apple Music / Spotify / YouTube link>. WolfWave finds the track (resolving Spotify and YouTube links to the matching Apple Music song) and adds it to the queue.
• Queue Panel: See every pending request right in Settings. Reorder or remove with a click.
• Approve first (optional): Turn on Require My Approval in Settings → Song Requests → Access and every request (chat, channel points, bits) waits in the queue for your OK before it plays. Off by default.
• Fair-share ordering: The queue plays round-robin, so everyone's first request comes before anyone's second. A regular who re-types fast can't play back-to-back while newcomers wait. On by default; flip Fair-Share Ordering off in Settings → Song Requests → Queue for classic first-in, first-out.
• Sub / VIP priority (optional): Reward subs, VIPs, and mods in Settings → Song Requests → Queue. Skip cooldown lets them request without the wait; Jump the queue also moves their song ahead of regular requests within the same fair-share round. Off by default.
• Hold Mode: Pause the whole queue from the menu bar or !hold. Requests still pile up, just nothing plays until you resume.
• Vote-skip: Chat skips the current song together with !voteskip. Counts up a chat tally or opens a real Twitch poll. Set the threshold in Settings → Song Requests → Chat Vote-Skip.
• Mod controls: Trusted users run !skip (jump to the next request) and !clearqueue (wipe the queue) from chat.
• Blocklist: Block specific tracks, artists, or albums you never want played.
• Quick Access: Hold/resume the queue directly from the menu bar.
• Share the playlist (optional): Requests collect in the "WolfWave Requests" playlist. The last setup step lets you share it publicly so !playlist posts a live link in chat. Skip it if you'd rather not. If you ever delete or un-share that playlist, WolfWave spots it, turns !playlist off, and shows a "set up again" banner so chat never gets a dead link.

Streamer Mode

Flip Streamer Mode from the menu bar's Streamer Quick Actions before you go live. WolfWave masks the connected Twitch channel name, the overlay/widget URLs, the WebSocket URI, and the auth token across every settings view. Copy/Open buttons next to masked values are disabled so screenshots can't reveal the underlying value via accessibility.

Streamer Mode is UI-only. Your WebSocket broadcast, Discord Rich Presence, and Twitch chat output keep working as usual.

Discord Status

When Discord Status is on, WolfWave updates your Discord profile to "Listening to WolfWave", with Apple Music album art and the track.

• Album Art: High-res artwork auto-fetched.
• Progress Bar: Shows where you are in the song.
• No Setup: As long as Discord is open, WolfWave finds it.

Settings

From the menu bar, open Settings to:

• General: Music sync, look and dock, notification banners.
• Stream Widgets: Port, themes, layouts, auth token.
• History & Stats: Listening history opt-in, Stats charts, Monthly Wrap.
• Twitch: Log in, pick commands, add custom commands, tweak cooldowns.
• Discord: Turn the profile status on/off.
• Song Requests: Queue, hold, blocklist, approval screening.
• Software Update: Check for updates, pick Stable or Nightly.
• Advanced: Backups, logs, diagnostics, or reset the setup wizard.