Settings

TL;DR: For streamers looking for a switch. Each section below is one Settings pane: what's in it and where to read more.

Open Settings: click the wolf icon in your menu bar, then Settings. The panes are listed in the sidebar.

Settings use native macOS switches with attached labels and wrapping descriptions. Disabled options follow the system appearance.

The toolbar names the selected pane. The window supports widths down to 640 points for compact or half-screen use, with integration status and actions stacked when needed. Hide the sidebar with its toolbar button to give the current pane more space.

Each pane also has a wolfwave:// link that opens WolfWave right to it. See Deep links.

GeneralCopy Anchor Link

How WolfWave tracks your music and where it shows up.

• Sync Music. The main switch. On by default. Shows what's playing and which services are connected.

  • Apple Music access denied? Click Open System Settings, allow it, then click Recheck.

• App Visibility.

  • Display Mode: Menu Bar Only, Dock Only, or Dock and Menu Bar.
  • Menu Bar Only temporarily shows the Dock icon while Settings is open.
  • Launch at Login: start WolfWave when you log in. If macOS blocks it, use Open Login Items.

• Appearance. Applies to the whole app, menu included.

  Option	What it does
  System (default)	Matches macOS, including its light/dark schedule.
  Light	Always light.
  Dark	Always dark.

• Notifications. Mac banners, all off by default:

  • Song change notifications
  • Skip vote started and Skip vote passed (turn on vote-to-skip in Song Requests first)

These preferences are included in Back Up & Restore.

Song RequestsCopy Anchor Link

Let chat request songs. How it all works: Song requests.

First time? Click Set Up Song Requests. The setup has these steps:

1. Get started. Checks Twitch. Not connected? Click Open Twitch Settings, sign in, then come back.
2. Apple Music access. Click Grant Apple Music Access. If you denied it before, turn on WolfWave in System Settings → Privacy & Security → Media & Apple Music. (This is separate from the Automation access that Sync Music uses.)
3. Requests playlist. Makes the WolfWave Requests playlist, then waits up to about 40 seconds for Music on this Mac to pick it up. Still not there? Turn on Music → Settings → General → Sync Library and click Check Again. You can finish setup either way.
4. Share link (optional). Lets !playlist post a link in chat.
5. All set.

Want to change something later? Click Run Setup Again under Enable Song Requests.

After setup, the pane groups its cards by task. The live queue stays near the top; request setup, playback behavior, and moderation follow below:

• Vote-Skip. Enable Vote-Skip, minimum votes, vote window, Subscriber-Only Voting, Use Twitch Polls. Works even with requests off.
• Song Request Queue. The live queue. Approve, remove, or Clear Requests to empty the queue and shared playlist together. If the queue is already empty, Music keeps playing. Songs stay in your library.
• Request Setup: Who Can Request sets a preset and approval; Song Request Commands manages !sr, !queue, !myqueue, !skip, !clearqueue, and !playlist; Channel Points & Bits configures paid requests.
• Queue Behavior: Queue Settings controls ordering, priority, capacity, and per-user limits. Playback controls Hold, Auto-Advance, Apple Music AutoPlay, and a fallback playlist. Enable AutoPlay in Music's Playing Next panel; a fallback playlist takes priority.

Queue controls sit above the song list. Use Hold before requests arrive or while the queue is active, then Resume when ready. Skip appears while a request is playing; Clear Requests asks before clearing the queue and shared playlist.

• Moderation: Blocklist blocks a Song, Artist, or Person. Press Return to add.

Per-user limits, explained:

• Each role (Everyone, subscribers, VIPs, and so on) can have its own limit.
• When a viewer has more than one role, choose:
  • Highest tier: they get their best role's limit.
  • Stacked: start from Everyone and add each role's extra slots.
• A role you haven't set shows None and adds nothing.

Chat commands: Bot Commands.

Stream WidgetsCopy Anchor Link

Your OBS overlay. Cards are in the order you need them:

1. Enable Stream Widgets. Starts the connection the overlay uses.
2. Widget Setup. Turn on Enable Widget Webpage, then Copy Link and paste it into OBS as a Browser Source. Network Address is for two-PC setups on a network you trust.
3. Widget Appearance. Theme, layout, colors, and font. Click Apply to update the overlay.
4. Build your own overlay. The raw feed: port, read-only overlay token, and addresses. Only needed for a hand-made overlay.

The header chip shows the server state:

• Listening (or N connected once an overlay joins)
• Starting
• Stopped
• Couldn't start. Usually a busy port. See Port already in use.

Other tips:

• To change the widget port, turn off the widget webpage first. A bad port is put back, and the field says Saved or Not saved.
• A greyed-out button tells you what to turn on first.

Sizes, themes, and messages: OBS Widget.

Stream DeckCopy Anchor Link

Control WolfWave from a Stream Deck.

• Allow Stream Deck commands. On by default. Turning it off leaves your overlay running.
• Stream Deck Control Token. Paste it into the plugin. Treat it like a password. It only works from this Mac.
• Stream Deck Setup Guide. Step-by-step setup.

Why it's separate from Stream Widgets: the overlay token is read-only and can reach across your network. The control token runs commands, so it only works on this Mac.

The header chip names the first thing in your way:

1. Server off. Turn on Stream Widgets.
2. Server error. The server couldn't start (often a busy port). Use Open Stream Widgets.
3. Starting.
4. Commands off. Turn on Allow Stream Deck commands.
5. Ready. Only shows when the server is really running.

Full walkthrough: Stream Deck.

History & StatsCopy Anchor Link

Your listening history, kept on this Mac.

• Listening History. Off by default. Turn it on to start recording plays.
• Show Stats & Charts. Weekly view, top artists, listening by hour, and the Monthly Wrap.
• !stats command. Pick the time window and what chat sees. Keep at least one item selected.
• Keep for. How long to keep plays. Choose Forever to keep them all.
• Danger Zone → Clear History. Deletes every play. Can't be undone.

What counts as a play: Listening History.

TwitchCopy Anchor Link

Connect your Twitch account and set up the chat bot.

Sign in:

1. Click Connect with Twitch.
2. Click Open twitch.tv/activate and enter the code. Codes expire after a few minutes; click Get a new code if needed.
3. Type your channel name and click Join Channel.

You never type your Twitch password into WolfWave.

Once you're in:

• Bot account shows who posts the replies.
• Log Out asks "Sign out of Twitch?" first.
• Only reply while live. Every command stays quiet until you go live. Off by default.
• Bot Commands. !song and !last are on for new installs. Turn on !wolfwave and Add a song.link here. Add aliases and set cooldowns.
• Custom Commands. Make your own commands. Each one can reply, post a plain message, or post an announcement. You can set these up before you connect; they reply once Twitch is connected.

Every command: Bot Commands.

DiscordCopy Anchor Link

Show what you're listening to on your Discord profile.

• Show on Discord. The main switch. Off by default.
• Profile Buttons. Up to two: Apple Music link and Any-app link (song.link). Both on by default.
• Playlist. Show playlist and Show playlist name.
• When the music isn't playing. Two choices, one per case:
  • When you pause: Keep the song (default) or Hide the song. A hidden song shows your "When music stops" choice.
  • When music stops: Listening to WolfWave (default) or Nothing.
• Preview. How your profile will look.

If it won't connect, the pane tells you why:

More fixes: Troubleshooting → Discord.

Software UpdateCopy Anchor Link

• Check Now looks for a new version.
• Check automatically looks in the background.
• Update Channel: Stable (recommended) or Nightly (dev). See Nightly Builds.
• Installed with Homebrew? Updates come from Homebrew instead.

Check for Updates… is also in the menu bar's Help menu.

AdvancedCopy Anchor Link

• Setup Wizard. Rerun Setup Wizard opens the wizard again. Your settings don't change.
• Share Diagnostics. Off by default. Keeps crash and performance reports on your Mac (the newest 50 from the last 30 days). Turning it off deletes them.
• Diagnostics (logs).
  • Export Logs saves one file: your setup (version, macOS, install method), the last crash, and every log.
  • Copy to Clipboard and Reveal in Finder.
  • Clear Logs erases the logs and starts fresh.
• Artwork Cache. Clear Artwork Cache forgets saved album art links. They're fetched again as songs play.
• Back Up Settings. Sync with iCloud, Export Settings, and Import Settings. See Back Up & Restore.
• Danger Zone. Erase All Data & Reset wipes every setting, sign-in, log, and cache, then restarts. Can't be undone.

If WolfWave crashed last time, a Recovered from a crash note appears here once, with Report a Bug….

AboutCopy Anchor Link

• Version and build info, with a copy button.
• Quick actions: Release Notes, Docs, Send Feedback, and Sponsor on GitHub.
• Show sponsor links. On by default. Turn it off to hide the Sponsor items here, in the menu bar, and in the Help menu. WolfWave works the same either way.
• Links & legal: Privacy, Terms, and Acknowledgements.

Deep linksCopy Anchor Link

A wolfwave:// link opens Settings on a pane, scrolls to a card, and flashes it.

• It works whether Settings is open or closed.
• A link WolfWave doesn't know opens General. It never shows an error.

wolfwave://settings                       General
wolfwave://settings/<pane>                one pane
wolfwave://settings/<pane>/<section>      one card inside that pane

The names below are fixed IDs, not the titles on screen, so links keep working when wording changes.

Some cards only show once a feature is on. Song Requests cards (except vote-skip) need setup done and requests on. History cards (except tracking) need Listening History on, and stats-command also needs Show Stats & Charts. A link to a hidden card opens the pane and stops there.

Try one from Terminal:

open "wolfwave://settings/twitch/custom-commands"

DebugCopy Anchor Link

Only in development builds. It has inspectors, service controls, a live log viewer, and UI previews for people working on WolfWave. Release builds don't have it.