This project is a background utility for macOS (tested on macOS 15 Tahoe/Sequoia) that allows you to control Spotify and Apple Music using network commands. It supports both the OSC (Open Sound Control) protocol and Raw UDP strings, making it compatible with everything from TouchOSC and Max/MSP to simple hardware triggers.
- Install: Double-click
Install.command. This will set up a private virtual environment and register the script to run automatically in the background when you log in. - Permissions: When you send your first command, macOS will ask for permission to control "Music" or "Spotify." You must click Allow.
- Check Status: Use
Check.commandat any time to see if the service is running and view recent logs. - Uninstall: Use
Uninstall.commandto completely remove the service and all associated files.
The bridge listens on all network interfaces (0.0.0.0) using the following ports:
| Protocol | Port | Description |
|---|---|---|
| OSC | 8000 |
Standard OSC messages with addresses and arguments. |
| UDP | 7000 |
Raw text strings (useful for simple hardware or netcat). |
| OSC Address | UDP Raw String Example | Argument / Payload |
|---|---|---|
/spotify/URL |
/spotify/URL <link> |
Spotify Web URL or URI |
/spotify/URI |
/spotify/URI <uri> |
spotify:track:XXXX |
/spotify/play |
/spotify/play |
(None) |
/spotify/pause |
/spotify/pause |
(None) |
/spotify/volume |
/spotify/volume 75 |
Integer (0-100) |
| OSC Address | UDP Raw String Example | Argument / Payload |
|---|---|---|
/music/URL |
/music/URL <link> |
Apple Music Album/Song URL |
/music/volume |
/music/volume 50 |
Integer (0-100) |
Note on UDP: For raw UDP, the command and the link must be separated by a space, for example:
"/spotify/URI spotify:playlist:1wVjx..."
If the logs show a missing module, the installation was likely interrupted. Run Uninstall.command and then Install.command again to rebuild the virtual environment.
- App Focus: The music app must be open (it can be in the background).
- Permissions: Go to System Settings > Privacy & Security > Automation and ensure your terminal/python has access to "Music" and "System Events."
If things aren't working, run Check.command. It will look for:
- PID: Is the script actually running?
- Listening Ports: Are Ports 8000/7000 open?
- Recent Errors: Did AppleScript return a syntax error?
listener.py: The core Python engine.Install.command: Creates thevenvand sets uplaunchd.Uninstall.command: Stops the service and deletes thevenv.Check.command: Diagnostic tool for troubleshooting.
Created by Cooper Santillan January 20, 2026 at 3:15pm