Skip to content

local-engine-boundary.md

Latest commit

 

History

History
101 lines (80 loc) · 2.96 KB

local-engine-boundary.md

File metadata and controls

101 lines (80 loc) · 2.96 KB
Raw

Local Engine Boundary

ORAM's Python engine remains the source of truth. The macOS app, dashboard, and DAW plug-ins speak to a local service boundary instead of mutating shared audio state directly.

Existing Engine Responsibilities

  • oram.config: environment and CLI configuration.
  • oram.app: terminal lifecycle wiring.
  • oram.command.parser: deterministic command grammar and optional LLM fallback.
  • oram.command.router: validated action dispatch, worker thread launch, and session mutation.
  • oram.audio: realtime/mock engine, layer manager, mixer, recorder, export.
  • oram.engines: provider registry, routing, adapters, and local mock engine.
  • oram.archive: session archive, command log, waveform text, listening report.
  • oram.web: optional dashboard using the same parser/router path.

Daemon Boundary

The daemon exposes a localhost HTTP API that translates app or plug-in requests into the same structured actions used by the terminal instrument.

Required routes:

GET  /health
GET  /state
GET  /library
GET  /providers
GET  /credentials/status
POST /command
POST /generate
POST /record/start
POST /record/stop
POST /export
POST /analyze
POST /credentials/test

The library routes extend that surface:

GET  /library/sounds
GET  /library/sounds/{id}
POST /library/sounds/{id}/favorite
POST /library/sounds/{id}/tags
POST /library/reveal

Plug-in clients that own their own realtime audio state use a non-mutating subset:

POST /actions/parse
POST /plugin/generate
GET  /stable-audio/modes
POST /stable-audio/render
POST /plugin/stable-audio/render

/actions/parse returns structured ORAM actions without routing them through the daemon's ActionRouter. /plugin/generate writes generated audio to the ORAM Library without assigning it to daemon layers.

/stable-audio/render exposes SA3-specific Generate, Morph, Continue, Inpaint, Latent, and LoRA Mixer requests. /plugin/stable-audio/render uses the same payload but never mutates daemon layers, so DAW, Max, and standalone clients can load the returned WAV into their own timeline or buffer model.

State Rules

  • /state is safe for UI refresh and must not expose credentials.
  • /credentials/status reports configured state and last test status only.
  • Generated sounds are written to the ORAM Library, then optionally assigned to an engine layer.
  • Slow work runs outside the realtime audio callback.
  • Stable Audio local/API rendering runs through provider adapters or a local sidecar service, never inside plugin DSP/audio callbacks.

Daemon Metadata

oram daemon writes:

~/Library/Application Support/ORAM/oram-daemon.json

Fields:

  • pid
  • host
  • port
  • started_at
  • version
  • auth_token_configured
  • metadata_path

When daemon auth is enabled, the metadata file also contains a generated local control token so the SwiftUI app can authenticate mutation requests. The file is written with owner-only permissions. It is not a provider credential store.