Cmts

Author: pblazej

Sources/LiveKit/Agent/Agent.swift

@@ -16,6 +16,20 @@
 
 import Foundation
 
+/// Represents a LiveKit Agent.
+///
+/// The ``Agent`` struct represents the state of a LiveKit agent within a ``Session``.
+/// It provides information about the agent's connection status, its current state
+/// (e.g., listening, thinking, speaking), and its media tracks.
+///
+/// The ``Agent``'s properties are updated automatically by the ``Session`` as the agent's
+/// state changes. This allows the application to react to the agent's
+/// behavior, such as displaying its avatar video or indicating when it is speaking.
+/// The ``agentState`` property is particularly useful for building UIs that reflect
+/// the agent's current activity.
+///
+/// - SeeAlso: [LiveKit SwiftUI Agent Starter](https://github.com/livekit-examples/agent-starter-swift).
+/// - SeeAlso: [LiveKit Agents documentation](https://docs.livekit.io/agents/).
 public struct Agent: Loggable {
     // MARK: - Error
 
@@ -25,7 +39,7 @@ public struct Agent: Loggable {
         public var errorDescription: String? {
             switch self {
             case .timeout:
-                "Agent not connected"
+                "Agent did not connect"
             }
         }
     }
@@ -44,7 +58,7 @@ public struct Agent: Loggable {
     // MARK: - Transitions
 
     mutating func disconnected() {
-        log("Agent disconnected from \(state)", .debug)
+        log("Agent disconnected from \(state)")
         // From any state
         state = .disconnected
     }
@@ -89,34 +103,39 @@ public struct Agent: Loggable {
 
     // MARK: - Public
 
+    /// A boolean value indicating whether the agent is connected.
     public var isConnected: Bool {
         switch state {
         case .connected: true
         default: false
         }
     }
 
+    /// The current conversational state of the agent.
     public var agentState: AgentState? {
         switch state {
         case let .connected(agentState, _, _): agentState
         default: nil
         }
     }
 
+    /// The agent's audio track.
     public var audioTrack: (any AudioTrack)? {
         switch state {
         case let .connected(_, audioTrack, _): audioTrack
         default: nil
         }
     }
 
+    /// The agent's avatar video track.
     public var avatarVideoTrack: (any VideoTrack)? {
         switch state {
         case let .connected(_, _, avatarVideoTrack): avatarVideoTrack
         default: nil
         }
     }
 
+    /// The last error that occurred.
     public var error: Error? {
         switch state {
         case let .failed(error): error

Sources/LiveKit/Agent/Chat/Receive/MessageReceiver.swift

@@ -20,8 +20,6 @@ import Foundation
 ///
 /// A message receiver is responsible for creating a stream of messages from the agent.
 /// It is used to receive messages from the agent and update the message feed.
-///
-/// - SeeAlso: ``ReceivedMessage``
 public protocol MessageReceiver: Sendable {
     func messages() async throws -> AsyncStream<ReceivedMessage>
 }

Sources/LiveKit/Agent/Chat/Send/MessageSender.swift

@@ -20,8 +20,6 @@ import Foundation
 ///
 /// A message sender is responsible for sending messages to the agent.
 /// It is used to send messages to the agent and update the message feed.
-///
-/// - SeeAlso: ``SentMessage``
 public protocol MessageSender: Sendable {
     func send(_ message: SentMessage) async throws
 }

Sources/LiveKit/Agent/Session.swift

@@ -18,6 +18,24 @@ import Combine
 import Foundation
 import OrderedCollections
 
+/// A ``Session`` represents a connection to a LiveKit Room that can contain an ``Agent``.
+///
+/// ``Session`` is the main entry point for interacting with a LiveKit agent. It encapsulates
+/// the connection to a LiveKit ``Room``, manages the agent's lifecycle, and handles
+/// communication between the user and the agent.
+///
+/// ``Session`` is created with a token source and optional configuration. The ``start()``
+/// method establishes the connection, and the ``end()`` method terminates it. The session's
+/// state, including connection status and any errors, is published for observation,
+/// making it suitable for use in SwiftUI applications.
+///
+/// Communication with the agent is handled through messages. The ``send(text:)`` method
+/// sends a user message, and the ``messages`` property provides an ordered history of the
+/// conversation. The session can be configured with custom message senders and receivers
+/// to support different communication channels, such as text messages or transcription streams.
+///
+/// - SeeAlso: [LiveKit SwiftUI Agent Starter](https://github.com/livekit-examples/agent-starter-swift).
+/// - SeeAlso: [LiveKit Agents documentation](https://docs.livekit.io/agents/).
 @MainActor
 open class Session: ObservableObject {
     private static let agentNameAttribute = "lk.agent_name"
@@ -40,9 +58,12 @@ open class Session: ObservableObject {
 
     // MARK: - Published
 
+    /// The last error that occurred.
     @Published public private(set) var error: Error?
 
+    /// The current connection state of the session.
     @Published public private(set) var connectionState: ConnectionState = .disconnected
+    /// A boolean value indicating whether the session is connected.
     public var isConnected: Bool {
         switch connectionState {
         case .connecting, .connected:
@@ -52,13 +73,16 @@ open class Session: ObservableObject {
         }
     }
 
+    /// The ``Agent`` associated with this session.
     @Published public private(set) var agent = Agent()
 
     @Published private var messagesDict: OrderedDictionary<ReceivedMessage.ID, ReceivedMessage> = [:]
+    /// The ordered list of received messages.
     public var messages: [ReceivedMessage] { messagesDict.values.elements }
 
     // MARK: - Dependencies
 
+    /// The underlying ``Room`` object for the session.
     public let room: Room
 
     private enum TokenSourceConfiguration {
@@ -98,6 +122,12 @@ open class Session: ObservableObject {
         observe(receivers: resolvedReceivers)
     }
 
+    /// Initializes a new ``Session`` with a fixed token source.
+    /// - Parameters:
+    ///   - tokenSource: A token source that provides a fixed token.
+    ///   - options: The session options.
+    ///   - senders: An array of message senders.
+    ///   - receivers: An array of message receivers.
     public convenience init(tokenSource: any TokenSourceFixed,
                             options: SessionOptions = .init(),
                             senders: [any MessageSender]? = nil,
@@ -109,6 +139,13 @@ open class Session: ObservableObject {
                   receivers: receivers)
     }
 
+    /// Initializes a new ``Session`` with a configurable token source.
+    /// - Parameters:
+    ///   - tokenSource: A token source that can generate tokens with specific options.
+    ///   - tokenOptions: The options for generating the token.
+    ///   - options: The session options.
+    ///   - senders: An array of message senders.
+    ///   - receivers: An array of message receivers.
     public convenience init(tokenSource: any TokenSourceConfigurable,
                             tokenOptions: TokenRequestOptions = .init(),
                             options: SessionOptions = .init(),
@@ -121,6 +158,15 @@ open class Session: ObservableObject {
                   receivers: receivers)
     }
 
+    /// Creates a new ``Session`` configured for a specific agent.
+    /// - Parameters:
+    ///   - agentName: The name of the agent to dispatch.
+    ///   - agentMetadata: Metadata passed to the agent.
+    ///   - tokenSource: A configurable token source.
+    ///   - options: The session options.
+    ///   - senders: An array of message senders.
+    ///   - receivers: An array of message receivers.
+    /// - Returns: A new ``Session`` instance.
     public static func withAgent(_ agentName: String,
                                  agentMetadata: String? = nil,
                                  tokenSource: any TokenSourceConfigurable,
@@ -173,6 +219,7 @@ open class Session: ObservableObject {
 
     // MARK: - Lifecycle
 
+    /// Starts the session.
     public func start() async {
         guard connectionState == .disconnected else { return }
 
@@ -210,16 +257,21 @@ open class Session: ObservableObject {
         }
     }
 
+    /// Terminates the session.
     public func end() async {
         await room.disconnect()
     }
 
+    /// Resets the last error.
     public func resetError() {
         error = nil
     }
 
     // MARK: - Messages
 
+    /// Sends a text message.
+    /// - Parameter text: The text to send.
+    /// - Returns: The ``SentMessage`` that was sent.
     @discardableResult
     public func send(text: String) async -> SentMessage {
         let message = SentMessage(id: UUID().uuidString, timestamp: Date(), content: .userInput(text))
@@ -233,10 +285,14 @@ open class Session: ObservableObject {
         return message
     }
 
+    /// Gets the message history.
+    /// - Returns: An array of ``ReceivedMessage``.
     public func getMessageHistory() -> [ReceivedMessage] {
         messages
     }
 
+    /// Restores the message history.
+    /// - Parameter messages: An array of ``ReceivedMessage`` to restore.
     public func restoreMessageHistory(_ messages: [ReceivedMessage]) {
         messagesDict = .init(uniqueKeysWithValues: messages.sorted(by: { $0.timestamp < $1.timestamp }).map { ($0.id, $0) })
     }

Sources/LiveKit/Agent/SessionOptions.swift

@@ -16,9 +16,17 @@
 
 import Foundation
 
+/// Options for creating a ``Session``.
 public struct SessionOptions: Sendable {
+    /// The undelying ``Room`` object for the session.
     public var room: Room
+    /// Whether to enable audio pre-connect with ``PreConnectAudioBuffer``.
+    /// If enabled, the microphone will be enabled before connecting to the room.
+    /// Use ``LocalMedia`` or ``AudioManager/setRecordingAlwaysPreparedMode(_:)``
+    /// to request microphone permissions early in the app lifecycle.
     public var preConnectAudio: Bool
+    /// The timeout for the agent to connect, in seconds.
+    /// If exceeded, the ``Agent`` will transition to a failed state.
     public var agentConnectTimeout: TimeInterval
 
     public init(

Sources/LiveKit/SwiftUI/LocalMedia.swift

@@ -18,6 +18,11 @@
 import Combine
 import Foundation
 
+/// An ``ObservableObject`` that can be used to control the local participant's media devices.
+///
+/// This class provides a convenient way to manage local media tracks, including enabling/disabling
+/// microphone and camera, and selecting audio and video devices. It is designed to be used
+/// in SwiftUI views.
 @MainActor
 open class LocalMedia: ObservableObject {
     // MARK: - Error
@@ -35,22 +40,34 @@ open class LocalMedia: ObservableObject {
 
     // MARK: - Devices
 
+    /// The last error that occurred.
     @Published public private(set) var error: Error?
 
+    /// The local microphone track.
     @Published public private(set) var microphoneTrack: (any AudioTrack)?
+    /// The local camera track.
     @Published public private(set) var cameraTrack: (any VideoTrack)?
+    /// The local screen share track.
     @Published public private(set) var screenShareTrack: (any VideoTrack)?
 
+    /// A boolean value indicating whether the microphone is enabled.
     @Published public private(set) var isMicrophoneEnabled: Bool = false
+    /// A boolean value indicating whether the camera is enabled.
     @Published public private(set) var isCameraEnabled: Bool = false
+    /// A boolean value indicating whether screen sharing is enabled.
     @Published public private(set) var isScreenShareEnabled: Bool = false
 
+    /// The available audio input devices.
     @Published public private(set) var audioDevices: [AudioDevice] = AudioManager.shared.inputDevices
+    /// The ID of the selected audio input device.
     @Published public private(set) var selectedAudioDeviceID: String = AudioManager.shared.inputDevice.deviceId
 
+    /// The available video capture devices.
     @Published public private(set) var videoDevices: [AVCaptureDevice] = []
+    /// The ID of the selected video capture device.
     @Published public private(set) var selectedVideoDeviceID: String?
 
+    /// A boolean value indicating whether the camera position can be switched.
     @Published public private(set) var canSwitchCamera = false
 
     // MARK: - Dependencies
@@ -59,17 +76,23 @@ open class LocalMedia: ObservableObject {
 
     // MARK: - Initialization
 
+    /// Initializes a new ``LocalMedia`` object.
+    /// - Parameter localParticipant: The ``LocalParticipant`` to control.
     public init(localParticipant: LocalParticipant) {
         self.localParticipant = localParticipant
 
         observe(localParticipant)
         observeDevices()
     }
 
+    /// Initializes a new ``LocalMedia`` object.
+    /// - Parameter room: The ``Room`` to control.
     public convenience init(room: Room) {
         self.init(localParticipant: room.localParticipant)
     }
 
+    /// Initializes a new ``LocalMedia`` object.
+    /// - Parameter session: The ``Session`` to control.
     public convenience init(session: Session) {
         self.init(room: session.room)
     }
@@ -116,6 +139,7 @@ open class LocalMedia: ObservableObject {
 
     // MARK: - Toggle
 
+    /// Toggles the microphone on or off.
     public func toggleMicrophone() async {
         do {
             try await localParticipant.setMicrophone(enabled: !isMicrophoneEnabled)
@@ -124,6 +148,8 @@ open class LocalMedia: ObservableObject {
         }
     }
 
+    /// Toggles the camera on or off.
+    /// - Parameter disableScreenShare: If `true`, screen sharing will be disabled when the camera is enabled.
     public func toggleCamera(disableScreenShare: Bool = false) async {
         let enable = !isCameraEnabled
         do {
@@ -138,6 +164,8 @@ open class LocalMedia: ObservableObject {
         }
     }
 
+    /// Toggles screen sharing on or off.
+    /// - Parameter disableCamera: If `true`, the camera will be disabled when screen sharing is enabled.
     public func toggleScreenShare(disableCamera: Bool = false) async {
         let enable = !isScreenShareEnabled
         do {
@@ -152,13 +180,17 @@ open class LocalMedia: ObservableObject {
 
     // MARK: - Select
 
+    /// Selects an audio input device.
+    /// - Parameter audioDevice: The ``AudioDevice`` to select.
     public func select(audioDevice: AudioDevice) {
         selectedAudioDeviceID = audioDevice.deviceId
 
         let device = AudioManager.shared.inputDevices.first(where: { $0.deviceId == selectedAudioDeviceID }) ?? AudioManager.shared.defaultInputDevice
         AudioManager.shared.inputDevice = device
     }
 
+    /// Selects a video capture device.
+    /// - Parameter videoDevice: The ``AVCaptureDevice`` to select.
     public func select(videoDevice: AVCaptureDevice) async {
         selectedVideoDeviceID = videoDevice.uniqueID
 
@@ -167,6 +199,7 @@ open class LocalMedia: ObservableObject {
         _ = try? await cameraCapturer.set(options: captureOptions)
     }
 
+    /// Switches the camera position.
     public func switchCamera() async {
         guard let cameraCapturer = getCameraCapturer() else { return }
         _ = try? await cameraCapturer.switchCameraPosition()