Quick start
- 1
Turn it on
Open the Mixer window and choose Control API. Allow control from other apps answers apps on this Mac only. - 2
Copy your token
The same page shows the address and your token. Press Copy. - 3
Send a request
This sets Spotify to 30 %:Terminalcurl -X POST http://127.0.0.1:48540/v1/setVolume \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"target": {"kind": "app", "id": "Spotify"}, "volume": 0.3}'
Address and token
http://127.0.0.1:48540/v1
If the port is taken, Mixer uses the next free one up to 48549 and shows it on the Control API page. To reach Mixer from a phone, a tablet or another computer, switch on Allow devices on this network and use the network address shown there.
Every request needs your token, as a header: Authorization: Bearer YOUR_TOKEN. A controller that can only open an address may add ?token=YOUR_TOKEN instead. New Token makes the old one stop working at once; the Stream Deck plugin picks up the new one by itself.
Scripts on this Mac can read the address and the token from ~/Library/Application Support/SoundRelay Mixer/control.json. The file is missing while control is off.
Targets
A target is your output (the master volume), your microphone, an app or a browser tab. Name an app by its name as Mixer shows it (not case-sensitive) or by its bundle id; a tab by the id from /v1/state.
{ "kind": "output" }
{ "kind": "input" }
{ "kind": "app", "id": "Spotify" }
{ "kind": "app", "id": "com.spotify.client" }
{ "kind": "tab", "id": "com.google.Chrome/1234" }Tabs are there while the Mixer extension is connected in that browser.
In /v1/state, app.permission is false until you allow Mixer to record system audio; app volumes are kept but not applied until then. output.software is true for outputs without a volume of their own (HDMI, many audio interfaces): Mixer then sets the master volume itself.
Endpoints
JSON in and out. Every POST body that changes something carries a target.
GET
/v1/stateYour output and microphone, every app that uses sound and each browser’s tabs: names, ids, volume, muted, playing.
- Answers
- The whole state
POST
/v1/setVolumeSets the volume, from 0.0 to 1.0, like the slider. For apps and tabs the sound follows the slider’s curve: 0.5 is about −12 dB.
- Body
- { "target": …, "volume": 0.3 }
- Answers
- { "volume": 0.3 }
POST
/v1/adjustVolumeAdds to the volume; a negative delta lowers it. 0.05 is 5 %.
- Body
- { "target": …, "delta": -0.05 }
- Answers
- { "volume": 0.25 }
POST
/v1/setMutedSets the mute.
- Body
- { "target": …, "muted": true }
- Answers
- { "muted": true }
POST
/v1/toggleMutedMutes or unmutes.
- Body
- { "target": … }
- Answers
- { "muted": false }
POST
/v1/setDefaultDeviceSwitches the Mac’s output or input device (uids from /v1/state).
- Body
- { "kind": "output", "uid": "…" }
- Answers
- { "uid": "…" }
GET
/v1/icon?app=…The app’s icon as a PNG (?tab=… for a tab’s site icon; &size= from 16 to 512, 144 by default).
- Answers
- image/png
As one link
For a controller that can only open an address, every action also works as a GET with its fields in the query: target (output, input, app or tab), id, volume, delta, muted=true|false and token.
http://127.0.0.1:48540/v1/toggleMuted?target=input&token=YOUR_TOKEN
http://127.0.0.1:48540/v1/adjustVolume?target=app&id=Discord&delta=-0.05&token=YOUR_TOKEN
Live state
The WebSocket sends the whole state when you connect and again on every change (at most 10 times a second), and takes the same methods. Send the token as the subprotocol mixer.YOUR_TOKEN.
const ws = new WebSocket("ws://127.0.0.1:48530/v1", "mixer.YOUR_TOKEN")
ws.onmessage = (e) => {
const m = JSON.parse(e.data)
if (m.event === "state") console.log(m.data.apps)
}
ws.onopen = () =>
ws.send(JSON.stringify({ id: 1, method: "toggleMuted", params: { target: { kind: "input" } } }))Answers carry the request’s id: { "id": 1, "result": { "muted": true } }. If the port is taken, Mixer uses the next free one up to 48539.
Trial and licence
Everything works for the 7 days of the trial. After that, without a licence, the output and the microphone still answer (state, volume, mute and the device switch); app and tab targets answer 402 licence_required./v1/state says which with app.locked.
Errors and limits
Errors are JSON: { "error": { "code": "not_found", "message": "…" } }
| Status | Code | Means |
|---|---|---|
| 400 | bad_request | A parameter is missing or wrong |
| 401 | unauthorized | The token is missing or wrong |
| 402 | licence_required | The trial is over and there is no licence (app and tab targets) |
| 403 | forbidden | The request came from a web page |
| 404 | not_found | No such app, tab, device or endpoint; an app that is not running is not found |
| 405 | method_not_allowed | Use GET for state and icon, GET or POST for the rest |
| 413 | too_large | The body is over 16 KB |
| 422 | not_supported | The microphone has no level or mute of its own |
| 500 | internal | Something went wrong in Mixer; try again |
Bodies up to 16 KB, sent with Content-Length; headers up to 8 KB; 10 seconds per connection; 32 connections at once. A refused connection means Mixer is not running: try again in a few seconds.
Keep it safe
- Requests from web pages are refused, so a website you visit cannot change your volume.
- Your token is made on your Mac and never leaves it. Treat it like a password; New Token replaces it.
- Leave network access off unless a phone or another computer needs it.