Jam Tracks Hub - YouTube Helper for Mac

Why this helper is needed
YouTube often blocks cloud servers from downloading audio. The helper lets
Jam Tracks Hub analyze a YouTube link from your own computer instead.

First-time setup
1. Download jasper-youtube-helper-mac.zip.
2. Double-click the zip file to unzip it.
3. Open the extracted folder.
4. Double-click INSTALL_MAC_HELPER_PROTOCOL.command.
5. If macOS blocks the file, right-click INSTALL_MAC_HELPER_PROTOCOL.command
   and choose Open.
   If it still shows only Done / Move to Trash, open Terminal and run:

   xattr -dr com.apple.quarantine ~/Downloads/jasper-youtube-helper-mac

   Then double-click INSTALL_MAC_HELPER_PROTOCOL.command again.
6. Return to the Key Finder page.
7. If the browser asks whether to open the local YouTube Helper, choose Open/Allow.

Daily use after setup
1. Open the Jam Tracks Hub Key Finder page.
2. The page will try to start the helper automatically.
3. If the browser asks whether to open the local YouTube Helper, choose Open/Allow.
4. Keep the Terminal window open while analyzing YouTube links.

Manual fallback
If auto-start does not work, double-click START_YOUTUBE_HELPER_MAC.command.
Wait until it shows:

   Uvicorn running on http://127.0.0.1:8765

Then return to the Key Finder page and analyze the YouTube link.

Requirements
- macOS.
- Python 3.10 or newer is required. Python 3.13 from python.org is recommended
  because newer yt-dlp releases are needed when YouTube changes its download
  behavior.

If YouTube download fails with HTTP 403
Install Python 3.13 from https://www.python.org/downloads/macos/, then run
START_YOUTUBE_HELPER_MAC.command again. The helper will replace an old Python
3.9 .venv with a newer local environment and update yt-dlp.

Notes
- Auto-start uses the jasper-helper://start browser protocol. Browsers may ask
  for permission the first time because websites cannot silently open local
  apps without user approval.
- The helper runs on your own computer at http://127.0.0.1:8765.
- Temporary audio files are deleted after analysis finishes.
- Uploaded audio analysis on the website does not need this helper. The helper
  is only for YouTube link analysis.
