Automation

Fadenza can be driven from five places: the media keys, Shortcuts, AppleScript, a local HTTP API, and MCP. Your own global shortcuts are a sixth way to reach it without its window, and they work differently enough to be worth reading about separately — see keyboard shortcuts.

The four scripted interfaces — Shortcuts, AppleScript, the HTTP API and MCP — all go through the same internal command layer. None of them reaches into another’s state, and none of them contains behaviour of its own, so an action does the same thing whichever route you take it by, and turning one off breaks nothing else. Media keys are the exception: they reach the player directly through the system’s Now Playing machinery, not through the command layer.

Everything scripted talks to the Queue

Media keys aside, every automation interface — Shortcuts, AppleScript, the HTTP API, MCP — addresses the permanent Queue and never a saved playlist. There is no playlist selector in any of them, by design: it keeps the scripted surface small and it means a script cannot quietly modify a list you curated by hand.

Two consequences are worth knowing before you rely on them. A scripted next while a saved playlist is playing moves playback into the Queue. And remove refuses the whole request if any identifier in it is unknown, rather than removing the ones it recognises and reporting the rest.

A global shortcut is not one of these, and the first of those two consequences is exactly why. It is a second way to press the button, so it acts on whatever is playing wherever it lives — a global Next during a saved playlist advances within that playlist. Automation is for scripts, which can enumerate the Queue and only the Queue; a key under your finger should do what the button does.

Media keys and Now Playing

Nothing to set up. While Fadenza is the active Now Playing app, the play, previous and next keys control it, along with Control Centre, the Lock Screen, and the controls on Bluetooth headphones.

Shortcuts

Fadenza’s actions appear in the Shortcuts app and can be used in automations, on the menu bar, or from Siri. They cover the same vocabulary as everything below.

AppleScript

The AppleScript surface is deliberately small:

tell application "Fadenza"
    playpause
    next
    previous
    set sound volume to 60
    get current track
end tell

current track is read-only, and there is no queue manipulation through AppleScript in v1 — Shortcuts and the HTTP API both cover it, and the AppleScript machinery required to do it properly does not pay for itself.

The local HTTP API

A JSON-over-HTTP control surface for scripts on the same machine.

It is off by default. Turn it on in Settings, where you will also find the port and the access token.

Once on:

• It binds loopback only — 127.0.0.1 and ::1. It is never reachable from another machine on your network, and there is no setting that makes it so.
• Every request needs the token: Authorization: Bearer <token>.
• The token is stored in your Keychain. It is not in the session file and not in the logs.
• Settings can copy it, or rotate it. Rotating invalidates anything using the old one immediately.
• Paths are versioned under /v1/. Anything else returns 404 with no detail.

What you can ask it to do

status              currentTrack           queue(offset, limit)
play                pause                  toggle
next                previous               seek(seconds)
setVolume(value)    setMute(value)         select(id)
remove(ids)         clear                  setRepeat(mode)
setShuffle(value)   enqueue(urls)

Limits

Every one of these is enforced:

The request-rate limit is shared across every connection rather than tracked per connection, on purpose: each response closes its connection, so a per-connection limit would reset with every request and never actually bound anything. It is the real defence against a guessed token, backed by a 256-bit one to begin with.

Responses carry no filesystem paths and no raw system error codes.

enqueue takes web URLs only

enqueue accepts http and https URLs. It will not accept a local file path, and this is not an oversight.

Fadenza is sandboxed and has no standing access to your filesystem. If the API could ask it to open a local file, any process on the machine holding the token could use your own app to reach files it could not reach itself. Local files therefore enter Fadenza only through something you did: a drag, the Open panel or Finder — all of which land in the playlist you were looking at — or the fadenza:// URL scheme and a watched folder, both of which land in the Queue.

The same rule applies one level down — a playlist fetched from the web has its file:// entries rejected as it is parsed.

MCP

The MCP adapter exposes the same commands to an AI client, under the same token and the same limits. It is a translation layer and nothing more; if it ever needs a capability the others do not have, that capability is added to the command layer and everything gains it at once.

The fadenza:// URL scheme

Opening a fadenza:// URL hands audio to the running app. It is the simplest way for another application, a shell script, or a Shortcut to add something to the queue.