Skip to content

Mixer – SoundRelay

Control API

Turn an app down, mute a tab or the microphone from other apps and devices. The Stream Deck plugin uses this API; Bitfocus Companion, Touch Portal, Apple Shortcuts and your own scripts can too.

  • http://127.0.0.1:48540/v1
  • Bearer token
  • This Mac only, unless you allow your network
  • HTTP and WebSocket

Quick start

  1. 1

    Turn it on

    Open the Mixer window and choose Control API. Allow control from other apps answers apps on this Mac only.
  2. 2

    Copy your token

    The same page shows the address and your token. Press Copy.
  3. 3

    Send a request

    This sets Spotify to 30 %:
    Terminal
    curl -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

Address on this Mac
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.

JSON
{ "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/state

    Your output and microphone, every app that uses sound and each browser’s tabs: names, ids, volume, muted, playing.

    Answers
    The whole state
  • POST/v1/setVolume

    Sets 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/adjustVolume

    Adds to the volume; a negative delta lowers it. 0.05 is 5 %.

    Body
    { "target": …, "delta": -0.05 }
    Answers
    { "volume": 0.25 }
  • POST/v1/setMuted

    Sets the mute.

    Body
    { "target": …, "muted": true }
    Answers
    { "muted": true }
  • POST/v1/toggleMuted

    Mutes or unmutes.

    Body
    { "target": … }
    Answers
    { "muted": false }
  • POST/v1/setDefaultDevice

    Switches 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

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.

JavaScript
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": "…" } }

StatusCodeMeans
400bad_requestA parameter is missing or wrong
401unauthorizedThe token is missing or wrong
402licence_requiredThe trial is over and there is no licence (app and tab targets)
403forbiddenThe request came from a web page
404not_foundNo such app, tab, device or endpoint; an app that is not running is not found
405method_not_allowedUse GET for state and icon, GET or POST for the rest
413too_largeThe body is over 16 KB
422not_supportedThe microphone has no level or mute of its own
500internalSomething 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.