Automation API

Overview

Two surfaces, same state#

App Intents are the native macOS Shortcuts surface. Drag them into a Shortcut, speak them at Siri, or wire them into a Focus Filter. They get typed parameters, structured return values, and proper error dialogs when something goes wrong. They're the smoothest path for anyone living inside the Shortcuts ecosystem.

The audita:// URL scheme is the lowest-common-denominator surface for everything else. Anything that can fire a URL can drive it: Stream Deck's built-in System » Open action, Keyboard Maestro's Open URL, Hammerspoon's hs.urlevent.openURL, AppleScript's open location, open "audita://..." from the shell. Responses flow back through x-callback-url as flat snake_case query parameters in plain ASCII - no JSON parsing required on the consumer side.

Audita's state is single-sourced: the intents and URLs read and write through the same AppState. Starting a session via Siri, the menu bar, or the URL scheme is the same operation; the URL endpoints don't see a parallel reality.

Trying it from the shell

open "audita://spl?x-success=https://httpbin.org/get"
open "audita://session/start?daw=Logic%20Pro"
open "audita://monitoring/pause?duration=1800"

Unknown URLs return unknown_endpoint via x-error when an error URL is supplied, and are otherwise logged and ignored. The audio engine must be running for SPL and dose reads to populate; when it isn't, the relevant keys are simply absent from the payload (the request still succeeds).

App Intents

The seven intents#

All seven intents are gated on macOS 14 (Sonoma). They live under Audita in the Shortcuts app's action library. Every perform() resolves Audita's app state first and throws appNotReady if Audita is still finishing launch - the intent surfaces the error verbatim rather than returning silent zeros.

Reads

Writes - sessions

Writes - monitoring

Focus Filter

Start a Mixing Session#

Audita registers a Focus Filter called Start a Mixing Session. Wire it once and a Focus turning on starts a session automatically; the Focus turning off ends it.

1. Open System Settings → Focus → (pick a Focus) → Add Filter → Audita → Start a Mixing Session.
2. Optional: set a DAW label. It's recorded in the session as daw.
3. Turn the Focus on. Audita starts a session.
4. Turn the Focus off. Audita ends the session.

Carry-over rule

If a session was already running when the Focus activated, Audita leaves it alone - the filter only ends what it started. If you manually ended the session before the Focus turned off, the disable does nothing (no double-end). The carry-over state is in-memory only, so quitting Audita while the Focus is on loses it. Documented constraint.

Spotlight & Siri

Pinned phrases#

These phrases are baked into Audita's AppShortcutsProvider. They show up in Spotlight as you type and are recognised by Siri verbatim. ASCII only - if a phrase silently changes, it disappears from Spotlight.

Errors

Intent error vocabulary#

Intent errors surface in Shortcuts as plain-English dialogs and in Siri as spoken responses. They're pinned strings - the wording is stable across releases so a Shortcut that branches on the message text doesn't break. They share the snake_case error_code map the URL scheme uses, so an automation that mixes intents and URL calls sees one consistent vocabulary.

URL scheme

audita:// endpoints#

Four read endpoints, four write endpoints. Reads need an x-success callback to deliver their payload - without one, the request is silently dropped because there's no other return channel. Writes treat both callbacks as optional. Responses use flat snake_case query parameters in plain ASCII so they survive a round-trip through Shortcuts' "Get URL" step without percent-escape noise.

Read endpoints

Write endpoints

Chaining

x-callback-url#

Two optional query parameters on every endpoint:

Query items on the callback URL are appended in alphabetical order for deterministic logs and tests. Existing query items on your callback URL are preserved unchanged.

Example: write chain

Start a Logic Pro session and trigger a Stream Deck profile. Audita appends the new session payload to your success URL:

# What you fire:
audita://session/start?daw=Logic%20Pro&x-success=streamdeck://profile/mixing

# What Stream Deck receives (after the start completes):
streamdeck://profile/mixing?active=true&daw=Logic%20Pro&result=ok&start_iso8601=2026-05-16T14%3A02%3A11%2B02%3A00

Example: read chain

Read the full state dictionary into a Shortcut. The Shortcut receives every key as a URL query item - use Get value from URL for each one you care about.

audita://state?x-success=shortcuts://run-shortcut?name=PostExposure

URL-encoding the callback

Your x-success / x-error URLs are themselves embedded as query values inside the audita:// URL. If your callback contains its own =, &, or spaces, percent-encode the whole callback URL before pasting it in - otherwise the outer URL parser will split your callback at the first & and you'll lose everything past it.

# Wrong - the outer parser sees three top-level params on the audita:// URL:
audita://state?x-success=shortcuts://run-shortcut?name=Post&arg=foo

# Right - the callback URL is encoded as a single query value:
audita://state?x-success=shortcuts%3A%2F%2Frun-shortcut%3Fname%3DPost%26arg%3Dfoo

Shortcuts, Raycast, and Keyboard Maestro all expose this as "URL-encode" or "Percent encode" - apply it once when building the outer URL.

Errors

URL error codes#

When an endpoint fails and an x-error URL was supplied, Audita opens it with error_code and error_message appended. Codes are stable snake_case strings; branch on these, not on the message text.

Plain ASCII only. No en-dashes, em-dashes, or ellipses - so the message survives a round-trip through Shortcuts' "Get URL" step without %E2%80%93 escapes.

Cross-app

Studio-on ritual: a worked example#

The daily-driver cross-app flow: one Shortcut, a handful of steps, both apps coordinate. Open your DAW, start an Audita session, switch Lyra to your reference monitor level, optionally engage a Focus mode so notifications quiet down. Run it from a Stream Deck button, a hotkey, or "Hey Siri, start mixing".

The Shortcut, step by step

Shortcut: "Mix Setup"

1. Open App: Logic Pro                  (built-in Shortcuts action)

2. Start Mixing Session in Audita      (Audita intent)
   DAW: Logic Pro

3. Switch to Reference Level in Lyra   (Lyra intent)
   Slot: 1

4. Turn Focus On: Mixing               (built-in Shortcuts action)
   Until: Turned Off

One tap and the DAW is open, dose tracking is on, the Apollo monitor level is at your reference, and Mixing Focus is engaged. If you already use Audita's auto-start-on-DAW-launch, step 2 is redundant (auto-detection handles it) and the ritual collapses to three steps. The Focus step in (4) is optional; drop it if you don't use Focus modes.

The same flow via URL scheme

If you're driving the chain from Stream Deck or Keyboard Maestro instead of Shortcuts, the equivalent URL sequence:

# 1. Open the DAW (any "open this app" mechanism works -
#    Stream Deck's System » Open, Keyboard Maestro's Activate Specific App,
#    `open -a "Logic Pro"` from a shell).

# 2. Start the session.
open "audita://session/start?daw=Logic%20Pro"

# 3. Recall the reference slot on Lyra.
open "lyra://reference/2"

Requires Lyra 1.4 or later (URL scheme handler) and Audita 1.2 (App Intents and URL scheme).

When Lyra isn't installed, the in-app "Send to Lyra..." button is hidden and a subtle hint links to the Lyra product page. Audita works fully without Lyra.