[adamgell]

FineTune currently accepts a limited set of URL commands without returning completion results or publishing current state. This draft adds a reusable automation service and an opt-in, current-user Unix socket API, allowing control surfaces and scripts to use the same existing audio controls with explicit results and live snapshots.

The API exposes app volume/mute/boost, device and input controls, default/single/multiple output routing, EQ and presets, AutoEQ, loudness, app/device management, preferences and shortcuts, presentation, Bluetooth connection, and updater controls. api.describe advertises 79 typed methods, including queries and protocol operations. Existing URL behavior stays compatible. Settings effects work with the settings window closed.

Requests use versioned newline-delimited JSON with stable app/device identifiers and structured errors. Slow operations return operation IDs; batches await terminal outcomes in order and retain partial results. Full snapshots carry instance/revision metadata. The disabled-by-default transport uses private discovery/socket permissions, same-user peer checks, bounded framing/clients/queues, and immediate disable/reset gating. There is no network listener.

A separate Stream Deck plugin is one consumer; no Stream Deck dependency is added to FineTune. A reproducible custom-build script uses a distinct bundle/settings identity and disables stock updates only for that custom compile configuration, allowing local use while this contribution remains unmerged.

Validation:

• Full macOS hosted FineTune unit suite: TEST SUCCEEDED (1,016 successful case entries in the final log).
• Added protocol, adapters, async operations, batch sequencing/failure, revision, state, socket, discovery and lifecycle regression tests, including a real Unix-socket roundtrip.
• Custom Release build completed; local ad-hoc signature verified with codesign --verify --deep --strict.
• Independent read-only review found eight Important issues; all were fixed and covered by regression checks. No Critical issue was reported. This is not a claim of exhaustive live validation.

Physical XL/audio acceptance, two outputs/five simultaneous apps, hot-plug, DDC hardware behavior, and latency/playback measurements remain unperformed. The supplied acceptance guide records these gaps. The custom distribution is not notarized. This PR is deliberately a draft pending those checks and maintainer architectural review.

Related existing work: #205 (Stream Deck/WebSocket integration), #217 (device-output URL level), and #445 (URL volume/DDC fixes). This uses a transport-independent service and local socket; it is not based on or tested together with those open changes. The modular commits separate protocol, app controls, other adapters, operations/state, transport/lifecycle, and regressions. I can split the contribution according to maintainer preferences.