feat: let the widget host pick voice, text, or both

.gitignore

@@ -7,3 +7,5 @@ xcuserdata/
 xcshareddata/
 Package.resolved
 *.bak
+DerivedData/
+*.xcuserstate

Documentation/Usage.md

@@ -64,18 +64,20 @@ conversation.$agentState
 
 ### Connection State
 
-Handle transitions between idle, connecting, connected, and ended states.
+Handle transitions between idle, connecting, connected, ended, and error states.
+Startup stages are nested under `.connecting`.
 
 ```swift
 conversation.$state
     .sink { state in
         switch state {
         case .idle:
             break
-        case .connecting:
-            break
+        case .connecting(let stage):
+            print("Connecting: \(stage)")
         case .connected(let callInfo):
             print("Connected to agent: \(callInfo.agentId)")
+            print("Conversation ID: \(callInfo.conversationId)")
         case .ended(let reason):
             print("Conversation ended: \(reason)")
         case .error(let error):
@@ -190,21 +192,29 @@ struct AudioControlView: View {
 }
 ```
 
-### Raw Audio Tracks
+### Raw Audio Observers
 
-Access the underlying LiveKit audio tracks for advanced visualization (e.g., audio visualizers or level meters).
+Observe decoded PCM from the agent output or local microphone without taking a LiveKit dependency in app code. Prefer this over reaching for transport tracks.
 
 ```swift
-// Use these with LiveKit view components or custom processors
-if let inputTrack = conversation.inputTrack as? LocalAudioTrack {
-    // Access local microphone track
+final class SpectrumObserver: ConversationAudioObserver, @unchecked Sendable {
+    func didReceive(_ buffer: AVAudioPCMBuffer) {
+        // Time-critical path: copy what you need, then hop off this callback.
+        let copy = buffer.copy()
+        Task { @MainActor in
+            updateVisualizer(copy)
+        }
+    }
 }
 
-if let agentTrack = conversation.agentAudioTrack as? RemoteAudioTrack {
-    // Access agent's audio track
-}
+let client = ConversationClient()
+let observer = SpectrumObserver()
+client.addAgentAudioObserver(observer)
+client.addMicAudioObserver(observer)
 ```
 
+`didReceive(_:)` runs on the audio callback path (not the main actor). The buffer is borrowed and read-only.
+
 ---
 
 ## Tool Calls
@@ -277,13 +287,17 @@ class ConversationViewModel: ObservableObject {
                 result = "Unknown tool: \(toolCall.toolName)"
             }
 
-            try await conversation.sendToolResult(for: toolCall.toolCallId, result: result)
+            try await conversation.sendToolResult(
+                .init(toolCallId: toolCall.toolCallId, result: result)
+            )
         } catch {
             print("Tool execution failed: \(error)")
             try? await conversation.sendToolResult(
-                for: toolCall.toolCallId,
-                result: "Error: \(error.localizedDescription)",
-                isError: true
+                .init(
+                    toolCallId: toolCall.toolCallId,
+                    result: "Error: \(error.localizedDescription)",
+                    isError: true
+                )
             )
         }
     }
@@ -484,10 +498,6 @@ let callbacks = ConversationCallbacks(
     onAudioAlignment: { alignment in
         // Real-time word highlighting timing.
     },
-    onCanSendFeedbackChange: { canSend in
-        // Enable/disable your 'Thumbs Up/Down' buttons in the UI
-        self.showFeedbackUI = canSend
-    },
     onError: { error in
         print("A non-fatal or startup error occurred: \(error)")
     }
@@ -519,20 +529,17 @@ let config = ConversationConfig(audioConfiguration: audioConfig)
 
 ---
 
-## Startup Performance Tuning {#startup-tuning}
+## Startup Timeouts {#startup-tuning}
 
-Control the connection handshake and retry behavior.
+Control how long startup waits for the agent and conversation metadata.
 
 ```swift
 let startupConfig = ConversationStartupConfiguration(
-    // Time to wait for agent to be 'ready' after room connection
+    // Time to wait for the agent after the room connects
     agentReadyTimeout: 10.0,
-
-    // Backoff strategy for protocol initialization 
-    initRetryDelays: [0, 1.0, 2.0, 5.0],
-
-    // Whether to fail early if agent takes too long
-    failIfAgentNotReady: true
+
+    // Time to wait for the server to initialize the conversation
+    initiationMetadataTimeout: 5.0
 )
 
 let config = ConversationConfig(startupConfiguration: startupConfig)
@@ -542,35 +549,29 @@ let config = ConversationConfig(startupConfiguration: startupConfig)
 
 ## Feedback & Context {#feedback-context}
 
-Handle feedback (like/dislike) and contextual updates to the agent.
+Feedback can be sent whenever the conversation is connected.
 
 ```swift
-// 1) Setup: react to feedback availability
-var canSendFeedback = false
-
 let callbacks = ConversationCallbacks(
     onAgentResponse: { text, eventId in
         print("Agent:", text, "(event:", eventId, ")")
-    },
-    onCanSendFeedbackChange: { can in
-        canSendFeedback = can
-        // e.g., refresh your UI
     }
 )
 
-let conversation = try await ElevenLabs.startConversation(agentId: "agent_123", callbacks: callbacks)
+let client = ConversationClient(callbacks: callbacks)
+_ = try await client.startConversation(agentId: "agent_123")
 
-// 2) Sending feedback from your UI
-func thumbsUp(latestEventId: Int) {
-    Task { try? await conversation.sendFeedback(.like, eventId: latestEventId) }
+func thumbsUp(eventId: Int) async throws {
+    guard client.state.isConnected else { return }
+    try await client.sendFeedback(.like, eventId: eventId)
 }
 
-func thumbsDown(latestEventId: Int) {
-    Task { try? await conversation.sendFeedback(.dislike, eventId: latestEventId) }
+func thumbsDown(eventId: Int) async throws {
+    guard client.state.isConnected else { return }
+    try await client.sendFeedback(.dislike, eventId: eventId)
 }
 
-// 3) Contextual updates (e.g., user preferences)
-Task { try? await conversation.updateContext("user_prefers_detailed_answers=true") }
+try await client.updateContext("user_prefers_detailed_answers=true")
 ```
 
 ---
@@ -609,7 +610,7 @@ class ReconnectionManager: ObservableObject {
                     self.showReconnectButton = false
                     self.isReconnecting = false
                     self.reconnectAttempts = 0
-                default:
+                case .idle, .connecting, .error:
                     break
                 }
             }
@@ -715,9 +716,7 @@ The SDK uses `os.Logger` for high-performance logging. You can filter logs in Xc
 Adjust the verbosity of the SDK:
 
 ```swift
-ElevenLabs.configure(
-    ElevenLabs.Configuration(logLevel: .debug) // .trace for full event logs
-)
+let client = ConversationClient(logLevel: .debug) // .trace for full event logs
 ```
 
 ---