========================================
   PULSE TUNES - Music Tool
   by nailedeet
========================================

WHAT IT DOES
------------
Shows what's playing on your PC on your OBS stream, with dynamic accent
colors that match your album art. Includes Twitch song requests (!sr and
Channel Point redemptions) that queue songs on Spotify or YouTube, plus
YouTube background music that plays when nobody has requested anything.


WIDGET SETUP
------------
1. Run PulseTunes.exe (look for the tray icon near the clock — click ^ if
   you don't see it)
2. Go to https://nailedeet.com/tools/music-widget-settings/
3. Customize the design and click "Copy OBS URL"
4. In OBS, add a Browser Source with that URL (650 x 200 works best)
5. Done — music shows on stream automatically

PulseTunes only runs one copy at a time. Launching twice shows an
"already running" message — check the tray instead.


SONG REQUESTS SETUP
-------------------
Two setups: an Audio Source (Spotify or YouTube) and Twitch. Both take
about 2 minutes from the tray menu.

Viewers request with either:
  * Chat command:  !sr <song>
  * Channel Points: redeem a reward you create on Twitch


STEP 1 — CHOOSE YOUR AUDIO SOURCE
---------------------------------
Right-click tray → "Music Source" → pick one:

Spotify (Premium required for queueing)
  Follow the on-screen steps. You'll create a free app on
  developer.spotify.com, paste the Redirect URI
  http://127.0.0.1:8888/callback into the app settings, then copy the
  Client ID into PulseTunes and click "Link Spotify".

YouTube (plays natively inside PulseTunes)
  No companion apps or browser required. Audio downloads to your Temp
  folder only while playing and is deleted automatically. The player
  window can stay hidden if you only want audio.


STEP 2 — LINK TWITCH
--------------------
1. Tray → "Twitch"
2. Register an app at dev.twitch.tv/console/apps
3. Set the OAuth Redirect URL to http://localhost:8889/callback
4. Log out of Twitch in your browser FIRST if linking a different account
5. Paste Client ID + Secret, click "Link Twitch", approve in browser
6. Fill in your channel name (no #) and bot username
7. Click Connect

If you only use !sr, you only need the Bot account linked.


STEP 3 (OPTIONAL) — CHANNEL POINT REDEMPTIONS
---------------------------------------------
1. In your Twitch Creator Dashboard, create a Custom Reward
   (e.g. "Song Request")
2. CRITICAL: enable "Require Viewer to Enter Text" on that reward — without
   it, viewers have nowhere to type the song name
3. In the PulseTunes Twitch dialog: check "Enable Channel Point
   Redemptions", click "Load Rewards", pick your reward, then Connect
4. Dialog should show "Redemptions: Connected"

Redemptions queue songs exactly like !sr and reply in chat the same way.


YOUTUBE BACKGROUND MUSIC
------------------------
Keeps music playing when nobody has requested anything

Setup:
1. Tray → "YouTube Player"
2. Paste a playlist URL (or a raw playlist ID starting with PL/UU/OL/...)
3. Tick "Enable: play this playlist when the queue is empty"
4. Changes save automatically

Behavior:
  - Viewer requests always cut the background track immediately — no
    waiting behind a 2-hour mix
  - When the queue empties, the next playlist track starts
  - The playlist loops
  - "▶ Play Now" forces the first playlist track to the front of the queue
  - Playlist resolution takes 1–10 seconds on first play

Playlist tracks appear in the OBS widget like any other song — title,
artist, and cover art.


YOUTUBE PLAYER WINDOW
---------------------
Contains Pause/Play, Skip, Volume (independent of Windows system volume),
Play Now, and the Background Music panel. Close to hide; re-open from the
tray menu.


CHAT RESPONSES
--------------
  !sr never gonna give you up
  → @viewer queued: Never Gonna Give You Up — Rick Astley
  → @viewer your song is now playing: Never Gonna Give You Up — Rick Astley

  Cooldown:      @viewer wait 87s before requesting again
  Queue full:    @viewer the queue is full (10 max). Try again later.
  Not found:     @viewer couldn't find that track


SONG REQUEST SETTINGS
---------------------
In the Twitch dialog:

  Cooldown (seconds)        Per-user rate limit. Default: 120
  Max queue length          Cap on pending requests. Default: 10
  Enable !sr                Toggles the chat command
  Enable Redemptions        Toggles reward redemptions
  Song Request reward       Which reward to listen for

The two Enable checkboxes and the reward dropdown save immediately.
Cooldown / Max queue apply on Connect.


TRAY MENU
---------
  Configure Widget · Music Source · YouTube Player · Twitch
  Change Port · Check for Updates · About · Exit


CUSTOM PORT
-----------
If port 8088 conflicts with another app:

1. Tray → Change Port → enter a new port (1024–65535) → Save & Restart
2. Update the Port field on the widget settings page and regenerate your
   OBS URL

The port affects the WIDGET only. Song requests use fixed ports 8888
(Spotify) and 8889 (Twitch).


TROUBLESHOOTING
---------------

"Pulse Tunes is already running"
  PulseTunes runs one copy at a time. Look for the tray icon (click ^).
  If stuck, end "PulseTunes" / "MusicNowPlaying" in Task Manager.

Widget not showing music
  - Confirm music is playing in a supported app
  - Confirm the port in your OBS Browser Source matches the app
  - Restart PulseTunes and refresh the OBS source

Song requests not working
  - Twitch dialog should show "Connected" — if not, click Connect
  - Music Source must have Spotify or YouTube selected
  - If the bot never replies in chat, re-link Twitch (may be missing
    chat:edit scope)

"Spotify queue error"
  - Spotify Premium is required
  - Spotify must be open and playing on the streamer's PC
  - If you switched to YouTube, click "Save & Reconnect Twitch" in Music
    Source

Redemptions not triggering
  - "Enable Channel Point Redemptions" must be checked
  - Dialog must show "Redemptions: Connected"
  - Reward must be selected via "Load Rewards"
  - Reward must have "Require Viewer to Enter Text" enabled

YouTube issues
  - "Unknown title" → re-download the latest PulseTunes.exe
  - Song doesn't play → video may be age-restricted, region-locked, or
    have embedding disabled; PulseTunes skips these silently
  - Background music isn't starting → confirm the checkbox is ticked and
    the playlist URL is valid (starts with PL/UU/OL/...)
  - "Play Now" fails → playlist is probably PRIVATE; set it to PUBLIC or
    UNLISTED
  - Player window is annoying → uncheck "Show YouTube player window" in
    Music Source


DATA STORAGE
------------
Everything stays on your PC, next to PulseTunes.exe:

  PulseTunes.config   Plaintext settings (port, client IDs, channel, bot,
                      cooldown, max queue, backend, playlist URL). Never
                      contains tokens.
  spotify_token.dat   Encrypted refresh token (Windows DPAPI)
  twitch_token.dat    Encrypted refresh token + client secret (DPAPI)

Encrypted files can only be decrypted by the same Windows user on the
same machine. Copying to another PC requires re-linking.

Downloaded YouTube audio is written to %TEMP%\pulse_tunes_* and deleted
when each track ends, is skipped, or on shutdown. Crash leftovers are
swept on next launch (anything older than 1 hour).


VERSION HISTORY
---------------
1.12.3 (current)
  - Smarter Spotify song matching: "artist - title" syntax now works,
    typos and abbreviations match intelligently, and mismatched garbage
    requests are rejected instead of queueing a random track
  - UI text accuracy and clipping fixes; clearer error messages
  - Fixed a rare audio file handle leak in the YouTube player
  - Internal refactor for stability and maintainability

1.12.0
  - YouTube requests use a native audio player (no WebView2)
  - YouTube Background Music (playlist plays when queue is empty)
  - Pause now signals the OBS widget correctly
  - Cover art for YouTube tracks (widget + accent color)
  - No additional runtime requirements

1.11.0
  - Channel Point Redemptions for song requests
  - Single-instance protection and startup confirmation
  - New scope: channel:read:redemptions

1.10.0
  - Twitch !sr song requests, per-user cooldown, max queue cap

1.1.0
  - Custom port via tray menu
  - Automatic update checker


NEED HELP?
----------
Website:        https://nailedeet.com
Widget config:  https://nailedeet.com/tools/music-widget-settings/