Automation

Fadenza can be driven from five places: the media keys, Shortcuts, AppleScript, a local HTTP API, and MCP.

All five 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 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 0.6
    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:

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 the queue only through something you did: a drag, the Open panel, Finder, the URL scheme, or a watched folder.

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.