release: add Stable Audio 3 local workflow

Author: emeisazam

.env.example

@@ -23,6 +23,11 @@ ORAM_DEFAULT_ENGINE=
 # engine router
 ORAM_ENGINE_ROUTER_MODE=auto
 ORAM_PREFERRED_PROVIDER=
+ORAM_STABLE_AUDIO_SERVICE_URL=http://127.0.0.1:8765
+ORAM_STABLE_AUDIO_LOCAL_PROVIDER=stable_audio_mlx
+ORAM_STABLE_AUDIO_LOCAL_MODEL=sm-music
+ORAM_STABLE_AUDIO_DECODER=same-s
+ORAM_STABLE_AUDIO_API_URL=
 
 # dashboard security
 ORAM_DASHBOARD_TOKEN=

README.md

@@ -111,8 +111,9 @@ recorder → looper → sampler → engine router → local archive
   normalize, trim, fades, and spatial transforms.
 - Listens back — spectral analysis of pitch, BPM, key, harmonics, and frequency
   character through local FFT, LLM-based interpretation, or hybrid routes.
-- Generates sound through Local Mock by default, or summons textures through
-  BYOK providers (ElevenLabs, Stability AI, fal Stable Audio).
+- Generates sound through Local SA3 by default when the local service is
+  available, or summons textures through BYOK providers (ElevenLabs, Stability
+  AI, fal Stable Audio).
 - Writes generated sounds into `~/Music/ORAM Library`.
 - Archives sessions as traces of a state: mix/stem WAVs, command logs, metadata,
   waveform text, and listening reports.
@@ -270,7 +271,8 @@ workstation." That is the intended boundary:
 - No ORAM cloud account is required.
 - The app talks to a localhost daemon.
 - Provider keys are stored in macOS Keychain for the packaged app.
-- Local Mock remains available without cloud credentials.
+- Local SA3 is the default local generation path; Local Mock remains available
+  only as an explicit fallback.
 - Telemetry is off by default.
 - Generated sounds and archives stay in the local ORAM Library.
 - Daemon mutation routes use a local bearer token when auth is enabled.
@@ -420,7 +422,7 @@ Current plugin features:
 - four native layers with record, overdub, mute, solo, clear, volume, and pan
 - loop regions and host-input monitoring
 - typed ORAM command parsing through the daemon
-- generation through Local Mock, ElevenLabs, or Stability routing, then WAV
+- generation through Local SA3, ElevenLabs, or Stability routing, then WAV
   import into native plugin layers
 - native state serialization for parameters and layer audio
 - basic plugin-side DSP actions including reverse, speed/pitch-ratio, filters,

apps/macos/Sources/ORAMApp/Models/Models.swift

@@ -240,6 +240,48 @@ struct ProvidersResponse: Decodable {
     let available: Int
 }
 
+struct AudioDevice: Decodable, Identifiable {
+    let id: Int
+    let name: String
+    let maxInputChannels: Int
+    let maxOutputChannels: Int
+    let defaultSamplerate: Double
+    let isInput: Bool
+    let isOutput: Bool
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case name
+        case maxInputChannels = "max_input_channels"
+        case maxOutputChannels = "max_output_channels"
+        case defaultSamplerate = "default_samplerate"
+        case isInput = "is_input"
+        case isOutput = "is_output"
+    }
+}
+
+struct DevicesResponse: Decodable {
+    let devices: [AudioDevice]
+    let defaultInput: Int
+    let defaultOutput: Int
+    let currentInput: Int?
+    let currentOutput: Int?
+    let currentSampleRate: Int
+    let currentFormat: String
+    let currentBitDepth: Int
+
+    enum CodingKeys: String, CodingKey {
+        case devices
+        case defaultInput = "default_input"
+        case defaultOutput = "default_output"
+        case currentInput = "current_input"
+        case currentOutput = "current_output"
+        case currentSampleRate = "current_sample_rate"
+        case currentFormat = "current_format"
+        case currentBitDepth = "current_bit_depth"
+    }
+}
+
 struct SoundRecord: Decodable, Identifiable {
     let id: String
     let createdAt: String
@@ -294,6 +336,77 @@ struct GeneratePayload: Encodable {
     }
 }
 
+struct StableAudioLoraPayload: Encodable {
+    let name: String
+    let path: String
+    let strength: Double
+    let interval: [Double]?
+}
+
+struct StableAudioRenderPayload: Encodable {
+    let prompt: String
+    let mode: String
+    let duration: Double
+    let provider: String
+    let model: String
+    let decoder: String
+    let localProvider: String
+    let localModel: String
+    let serviceURL: String
+    let chunkedDecode: Bool
+    let sourceLayer: Int?
+    let targetLayer: String?
+    let assignLayer: Bool
+    let tags: [String]
+    let negativePrompt: String
+    let seed: Int?
+    let steps: Int
+    let cfgScale: Double
+    let noiseDepth: Double?
+    let inpaintStart: Double?
+    let inpaintEnd: Double?
+    let variationCount: Int
+    let loraStack: [StableAudioLoraPayload]
+    let loraAPath: String
+    let loraAStrength: Double
+    let loraBPath: String
+    let loraBStrength: Double
+    let loraIntervalMin: Double
+    let loraIntervalMax: Double
+
+    enum CodingKeys: String, CodingKey {
+        case prompt
+        case mode
+        case duration
+        case provider
+        case model
+        case decoder
+        case localProvider = "local_provider"
+        case localModel = "local_model"
+        case serviceURL = "service_url"
+        case chunkedDecode = "chunked_decode"
+        case sourceLayer = "source_layer"
+        case targetLayer = "target_layer"
+        case assignLayer = "assign_layer"
+        case tags
+        case negativePrompt = "negative_prompt"
+        case seed
+        case steps
+        case cfgScale = "cfg_scale"
+        case noiseDepth = "noise_depth"
+        case inpaintStart = "inpaint_start"
+        case inpaintEnd = "inpaint_end"
+        case variationCount = "variation_count"
+        case loraStack = "lora_stack"
+        case loraAPath = "lora_a_path"
+        case loraAStrength = "lora_a_strength"
+        case loraBPath = "lora_b_path"
+        case loraBStrength = "lora_b_strength"
+        case loraIntervalMin = "lora_interval_min"
+        case loraIntervalMax = "lora_interval_max"
+    }
+}
+
 struct GenerateResponse: Decodable {
     let status: String
     let sound: SoundRecord?

apps/macos/Sources/ORAMApp/Services/DaemonClient.swift

@@ -34,6 +34,10 @@ final class DaemonClient {
         try await get("/providers")
     }
 
+    func devices() async throws -> DevicesResponse {
+        try await get("/devices")
+    }
+
     func credentialStatus() async throws -> [String: CredentialStatus] {
         try await get("/credentials/status")
     }
@@ -59,6 +63,10 @@ final class DaemonClient {
         try await post("/generate", payload: payload)
     }
 
+    func stableAudioRender(_ payload: StableAudioRenderPayload) async throws -> GenerateResponse {
+        try await post("/stable-audio/render", payload: payload)
+    }
+
     func recordStart() async throws {
         let payload = ["target": "selected"]
         let _: EmptyResponse = try await post("/record/start", payload: payload)

apps/macos/Sources/ORAMApp/Stores/AppStore.swift

@@ -6,6 +6,7 @@ final class AppStore: ObservableObject {
     @Published var health: Health?
     @Published var state: EngineState?
     @Published var providers: [ProviderEngine] = []
+    @Published var devices: DevicesResponse?
     @Published var credentials: [String: CredentialStatus] = [:]
     @Published var sounds: [SoundRecord] = []
     @Published var waveforms: [Int: WaveformPeaks] = [:]
@@ -43,6 +44,7 @@ final class AppStore: ObservableObject {
             let nextState = try await client.state()
             state = nextState
             providers = try await client.providers().engines
+            devices = try await client.devices()
             credentials = try await client.credentialStatus()
             sounds = try await client.sounds().sounds
             await refreshWaveforms(for: nextState)
@@ -86,6 +88,21 @@ final class AppStore: ObservableObject {
         }
     }
 
+    func stableAudioRender(_ payload: StableAudioRenderPayload) async {
+        guard !payload.prompt.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else { return }
+        isGenerating = true
+        defer { isGenerating = false }
+        do {
+            let response = try await client.stableAudioRender(payload)
+            if let sound = response.sound {
+                selectedSoundID = sound.id
+            }
+            await refreshAll()
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+
     func startRecording() async {
         do {
             try await client.recordStart()
@@ -207,9 +224,14 @@ final class AppStore: ObservableObject {
         }
     }
 
-    func updateAudioSettings(sampleRate: Int?, blockSize: Int?) async {
+    func updateAudioSettings(sampleRate: Int?, blockSize: Int?, inputDevice: Int? = nil, outputDevice: Int? = nil) async {
         do {
-            try await client.updateSettings(sampleRate: sampleRate, blockSize: blockSize)
+            try await client.updateSettings(
+                sampleRate: sampleRate,
+                blockSize: blockSize,
+                inputDevice: inputDevice,
+                outputDevice: outputDevice
+            )
             await refreshAll()
         } catch {
             errorMessage = error.localizedDescription