Features

TL;DR: A tour of every WolfWave feature for streamers. Each section says what it does, how to turn it on, and where to read more.

Haven't installed yet? Start with Install.

Menu bar and Music SyncCopy Anchor Link

WolfWave lives in your menu bar. Click the wolf icon to see:

• What's playing, with album art.
• Quick switches for Apple Music, Twitch, Discord, the OBS overlay, and Streamer Mode.
• Song request controls: hold or resume, skip, and clear the queue and shared playlist.
• Clear Requests empties the queue and WolfWave Requests together. Music keeps playing when the queue is already empty. The songs stay in your Apple Music library; the !playlist link shows an empty playlist until new requests arrive.

How it works:

• Music Sync is the main switch. It's in Settings → General → Sync Music. It's on by default.
• Apple Music only. WolfWave asks Apple Music directly. It doesn't read other players.
• Battery friendly. It checks less often in Low Power Mode.
• Asks before risky actions. Clear Queue… and Restart Integrations… confirm first.

Twitch chat botCopy Anchor Link

Let chat ask what's playing.

Turn it on:

1. Open Settings → Twitch and click Connect with Twitch.
2. Approve the code at twitch.tv/activate. You never type your password into WolfWave.
3. Type your channel name and click Join Channel.
4. Under Bot Commands, switch on the commands you want.

What you get:

• !song posts the current song. !last posts the one before. Both start off.
• !wolfwave tells chat what WolfWave is.
• Include song.link adds a link that works on any music service.
• Aliases. Add your own extra names for a command.
• Cooldowns stop spam. They don't apply to you or your mods.
• Only reply while live. Turn this on and every command stays quiet until you go live. Off by default.
• Custom commands. Make your own !command with a fixed reply. Variables like $user, $touser, $args, $song, and $lastsong fill in live. Each one has a permission level, a cooldown, and a choice of reply, plain message, or Twitch announcement. You can set them up before you connect.

Full list and defaults: Bot Commands.

Song requestsCopy Anchor Link

Let chat add songs to a queue that plays in Apple Music.

Turn it on:

1. Connect Twitch first (see above).
2. Open Settings → Song Requests and click Set Up Song Requests.
3. The setup checks Twitch, asks for Apple Music access, and makes a playlist called WolfWave Requests.
4. Optional: share that playlist so !playlist can post a link in chat.
5. Turn on requests when setup asks.

Requests can't turn on until setup is done. Nothing half-set-up goes live.

How viewers request:

• !sr <song name> searches Apple Music.
• !sr <link> works with Apple Music, Spotify, and YouTube links. WolfWave finds the matching Apple Music song.
• If a Spotify or YouTube link is unclear, WolfWave says no instead of guessing. Ask for the artist and title instead.

Who can request (the Who Can Request card):

Mods and you can always request.

Require My Approval (same card) holds every request until you approve or decline it in the queue. Off by default.

Queue rules (the Queue Settings card):

• Max queue size. 10 songs by default.
• Per-user limits. How many songs one viewer can have waiting. 2 by default. You can set a different limit per role.
• Fair-Share Ordering. Everyone's first request plays before anyone's second. On by default. Turn it off for first-come, first-served.
• Sub / VIP priority. Off by default. Skip cooldown lets subs, VIPs, and mods skip the wait. Jump the queue also moves them ahead in each round.

Playback (the Playback card):

• Auto-Advance Queue plays the next request when a song ends.
• Hold Queue pauses the queue. Requests still come in, but nothing plays until you resume. Also in the menu bar and the !hold / !resume commands.
• Fallback playlist plays an Apple Music playlist you pick when the queue is empty.
• Resume Apple Music AutoPlay hands playback back to Music when the queue empties. Turn on AutoPlay in Music's Playing Next panel first. A fallback playlist takes priority.

Blocklist:

• Block a Song, an Artist, or a Person.
• A blocked person is turned away before WolfWave even searches.
• Matching ignores capital letters, accents, and extra spaces.
• Artist blocks also catch collaborations (for example, a blocked artist inside "Artist A feat. Artist B").
• Heads up: it matches text. A short entry like Wind also blocks "Earth, Wind & Fire".

Vote-to-skip:

• Turn on Enable Vote-Skip. Chat types !voteskip (or !vs).
• Set the Minimum votes to skip (3 by default) and the vote window (60 seconds by default).
• Optional: Subscriber-Only Voting, or Use Twitch Polls for a native poll (Affiliate/Partner only).

Sync Library check:

• Songs play from the Music app on this Mac.
• The WolfWave Requests playlist only reaches Music if Sync Library is on (Music → Settings → General).
• WolfWave gives iCloud up to about 40 seconds to sync, then warns you if Music still can't see the playlist.

More: chat commands in Bot Commands, every switch in Settings.

Channel points and BitsCopy Anchor Link

These live in the Channel Points & Bits card. Enable the tools on Twitch, sign in with your broadcaster account, and grant the permissions WolfWave requests. Twitch must allow the API access needed for each feature; see the FAQ for eligibility details.

• Channel Point Requests. WolfWave makes a "Request a Song" reward for you (500 points by default). If a request fails (not found, blocked, queue full), the points go back automatically.
• Bit Requests. Viewers cheer with a song name to request it. Set the Minimum bits (100 by default).
• Boost With Bits. A cheer moves the viewer's oldest queued song to the front instead of adding a new one.
• Same rules as !sr. Points and Bits follow your audience, limits, blocklist, approval, and hold settings.
• Safe across crashes. WolfWave saves what it owes before it touches the queue. After a quit or outage it finishes the refund or the Bits action.

Now-playing widget (OBS overlay)Copy Anchor Link

Show the current song on stream. It runs on your Mac. No overlay website needed.

Turn it on:

Style it (the Widget Appearance card):

• Theme: Default, Dark, Light, Glass, or Neon.
• Layout: Horizontal, Vertical, Compact, Vinyl, or Classic.
• Text and Background colors (Default and Glass themes), and a Font.
• Click Apply to send changes to the overlay.

Extras:

• Queue ticker. Add ?queueTicker=1 to the link to show the next requests on screen.
• Two-PC setups. Use the Network Address link. Only use it on a network you trust.

Sizes, messages, and theming: OBS Widget. Security details: WebSocket security.

Stream DeckCopy Anchor Link

Control WolfWave from a Stream Deck. The official plugin has 12 keys: play/pause, skip, hold the queue, approve, reject, clear the queue, block a song or requester, change who can request, announce the song, toggle the overlay, and show what's playing.

• Every key shows live state.
• It uses its own control token that only works on this Mac.

Setup: Stream Deck. Building your own tool? See the Stream Deck Control API.

Discord statusCopy Anchor Link

Show "Listening to WolfWave" on your Discord profile, with album art and a live progress bar.

Turn it on:

1. Open the Discord app on this Mac.
2. Open Settings → Discord and turn on Show on Discord.

No bot, no token, no server. Off by default.

Options:

• Profile Buttons. Up to two buttons: an Apple Music link and an Any-app link (song.link). Both on by default.
• Show playlist. Shows the playlist you're playing from. Show playlist name off keeps the name private.
• When you pause. Keep the song (default) leaves it up with a paused badge. Hide the song shows your "When music stops" choice instead.
• When music stops. Listening to WolfWave (default) shows that line with no song. Nothing clears your status.

Listening history and statsCopy Anchor Link

• Off by default. Turn it on in Settings → History & Stats.
• Stays on your Mac. It's never uploaded.
• Counts real plays. A song counts after half its length or 4 minutes, so skips don't count.
• Charts and Monthly Wrap. Top artists, listening time, and a monthly summary you can share as an image.
• !stats for chat. Pick what it shows.

More: Listening History.

NotificationsCopy Anchor Link

Mac banners for:

• Song changes (with album art).
• Skip vote started and Skip vote passed (need vote-to-skip on).

All off by default. Turn them on in Settings → General. A new banner replaces the old one of the same kind.

Streamer ModeCopy Anchor Link

One click in the menu bar hides private info on screen. Your channel name, overlay links, and tokens show as ••••••. Everything keeps working. More: Streamer Mode.

Back up, restore, and iCloud syncCopy Anchor Link

• Export Settings saves your preferences to a file. Import Settings brings them back on a new Mac.
• Sync with iCloud keeps your preferences matched across your Macs.
• Sign-ins and tokens are never included. You sign in to Twitch once per Mac.

More: Back Up & Restore.

Diagnostics and bug reportsCopy Anchor Link

• Report a Bug (menu bar → Help) opens a GitHub issue with your app version filled in.
• Export Logs (Settings → Advanced) saves one file with your setup, the last crash, and your logs.
• Share Diagnostics is off by default. It keeps crash and performance data on your Mac until you share it. WolfWave keeps the newest 50 reports from the last 30 days, and deletes them when you turn it off.
• Error messages name the problem, offer a fix, and often link to Troubleshooting.

More: Report a bug.

Security and privacyCopy Anchor Link

• Sign-ins are stored in the macOS Keychain.
• No analytics. Data only goes to services you turn on.
• Signed and notarized by Apple.

More: Security and the Privacy Policy. Comparing tools? See the comparison.

Where to nextCopy Anchor Link