Swift SDK | ElevenLabs Documentation

すぐに始めるには、完全に動作するサンプルを含むSwiftクイックスタートプロジェクトをご確認ください。

インストール

Swift Package Managerを使用して、プロジェクトにElevenLabs Swift SDKを追加します。

パッケージ依存関係を追加

dependencies: [ .package(url: "https://github.com/elevenlabs/elevenlabs-swift-sdk.git",
from: "2.0.0") ]

またはXcodeを使用します。

Xcodeでプロジェクトを開きます
File＞Add Package Dependencies...に移動します
リポジトリURLを入力します：https://github.com/elevenlabs/elevenlabs-swift-sdk.git
バージョン2.0.0以降を選択します

SDKをインポート

import ElevenLabs

マイクへのアクセス理由をユーザーに説明するため、Info.plistにNSMicrophoneUsageDescriptionを追加してください。 SDKにはiOS 14.0以降／macOS 11.0以降およびSwift 5.9以降が必要です。

クイックスタート

わずか数行でシンプルな会話を始められます。会話をユーザーに紐付けるため、独自のエンドユーザーIDを渡すことをおすすめします。

import ElevenLabs
// Start a conversation with your agent
let conversation = try await ElevenLabs.startConversation(
    agentId: "your-agent-id",
    userId: "your-end-user-id",
    config: ConversationConfig()
)
// Observe conversation state and messages
conversation.$state
    .sink { state in
        print("Connection state: \(state)")
    }
    .store(in: &cancellables)
conversation.$messages
    .sink { messages in
        for message in messages {
            print("\(message.role): \(message.content)")
        }
    }
    .store(in: &cancellables)
// Send messages and control the conversation
try await conversation.sendMessage("Hello!")
try await conversation.toggleMute()
await conversation.endConversation()

認証

会話を認証して開始する方法は2つあります。

パブリックエージェント

プライベートエージェント

パブリックエージェントでは、エージェントIDを直接使用します。

let conversation = try await ElevenLabs.startConversation(
    agentId: "your-public-agent-id",
    config: ConversationConfig()
)

主な機能

リアクティブな会話管理

SDKは、リアクティブなUI更新のために@Publishedプロパティを備えたモダンなConversationクラスを提供します。

@MainActor
class ConversationManager: ObservableObject {
    @Published var conversation: Conversation?
    private var cancellables = Set<AnyCancellable>()
    func startConversation(agentId: String) async throws {
        let config = ConversationConfig(
            conversationOverrides: ConversationOverrides(textOnly: false)
        )
        conversation = try await ElevenLabs.startConversation(
            agentId: agentId,
            config: config
        )
        setupObservers()
    }
    private func setupObservers() {
        guard let conversation else { return }
        // Monitor connection state
        conversation.$state
            .sink { state in print("State: \(state)") }
            .store(in: &cancellables)
        // Monitor messages
        conversation.$messages
            .sink { messages in print("Messages: \(messages.count)") }
            .store(in: &cancellables)
    }
}

音声モードとテキストモード

// Voice conversation (default)
let voiceConfig = ConversationConfig(
    conversationOverrides: ConversationOverrides(textOnly: false)
)
// Text-only conversation
let textConfig = ConversationConfig(
    conversationOverrides: ConversationOverrides(textOnly: true)
)

オーディオコントロール

// Microphone control
try await conversation.toggleMute()
try await conversation.setMuted(true)
// Check microphone state
let isMuted = conversation.isMuted
// Access audio tracks for advanced use cases
let inputTrack = conversation.inputTrack
let agentAudioTrack = conversation.agentAudioTrack

クライアントツール

クライアントツールでは、会話中にAIエージェントから呼び出せるカスタム関数を登録できます。新しいSDKでは、パラメータ処理とエラー管理が改善されています。

ツール呼び出しの処理

完全なパラメータサポートで、エージェントからのツール呼び出しを処理します。

private func handleToolCall(_ toolCall: ClientToolCallEvent) async {
    do {
        let parameters = try toolCall.getParameters()
        let result = await executeClientTool(
            name: toolCall.toolName,
            parameters: parameters
        )
        if toolCall.expectsResponse {
            try await conversation?.sendToolResult(
                for: toolCall.toolCallId,
                result: result
            )
        } else {
            conversation?.markToolCallCompleted(toolCall.toolCallId)
        }
    } catch {
        // Handle tool execution errors
        if toolCall.expectsResponse {
            try? await conversation?.sendToolResult(
                for: toolCall.toolCallId,
                result: ["error": error.localizedDescription],
                isError: true
            )
        }
    }
}
// Example tool implementation
func executeClientTool(name: String, parameters: [String: Any]) async -> [String: Any] {
    switch name {
    case "get_weather":
        guard let location = parameters["location"] as? String else {
            return ["error": "Missing location parameter"]
        }
        // Fetch weather data
        return ["temperature": "22°C", "condition": "Sunny"]
    case "send_email":
        guard let recipient = parameters["recipient"] as? String,
              let subject = parameters["subject"] as? String else {
            return ["error": "Missing required parameters"]
        }
        // Send email logic
        return ["status": "sent", "messageId": "12345"]
    default:
        return ["error": "Unknown tool: \(name)"]
    }
}

ElevenLabs UIで、エージェントにクライアントツールを設定してください。設定手順については、クライアントツールのドキュメントをご覧ください。

接続状態の管理

会話の状態を監視して、さまざまな接続フェーズに対応します。

conversation.$state
    .sink { state in
        switch state {
        case .idle:
            // Not connected
            break
        case .connecting:
            // Show connecting indicator
            break
        case .active(let callInfo):
            // Connected to agent: \(callInfo.agentId)
            break
        case .ended(let reason):
            // Handle disconnection: \(reason)
            break
        case .error(let error):
            // Handle error: \(error)
            break
        }
    }
    .store(in: &cancellables)

エージェント状態の監視

エージェントがリスニング中か発話中かを追跡します。

conversation.$agentState
    .sink { state in
        switch state {
        case .listening:
            // Agent is listening, show listening indicator
            break
        case .speaking:
            // Agent is speaking, show speaking indicator
            break
        }
    }
    .store(in: &cancellables)

メッセージ処理

テキストメッセージを送信し、会話を監視します。

// Send a text message
try await conversation.sendMessage("Hello, how can you help me today?")
// Monitor all messages in the conversation
conversation.$messages
    .sink { messages in
        for message in messages {
            switch message.role {
            case .user:
                print("User: \(message.content)")
            case .agent:
                print("Agent: \(message.content)")
            }
        }
    }
    .store(in: &cancellables)

オーディオアラインメント

同期したテキスト表示のため、文字単位のタイミングデータを監視します。

// Using the callback
let config = ConversationConfig(
    onAudioAlignment: { alignment in
        // Character-level timing data
        for (index, char) in alignment.chars.enumerated() {
            let startMs = alignment.charStartTimesMs[index]
            let durationMs = alignment.charDurationsMs[index]
            print("'\(char)' at \(startMs)ms for \(durationMs)ms")
        }
    }
)
// Or observe the published property
conversation.$latestAudioAlignment
    .compactMap { $0 }
    .sink { alignment in
        // Handle alignment updates
    }
    .store(in: &cancellables)

セッション管理

// End the conversation
await conversation.endConversation()
// Check if conversation is active
let isActive = conversation.state.isActive

SwiftUIインテグレーション

新しいSDKを使用した包括的なSwiftUIの例を紹介します。

import SwiftUI
import ElevenLabs
import Combine
struct ConversationView: View {
    @StateObject private var viewModel = ConversationViewModel()
    var body: some View {
        VStack(spacing: 20) {
            // Connection status
            Text(viewModel.connectionStatus)
                .font(.headline)
                .foregroundColor(viewModel.isConnected ? .green : .red)
            // Chat messages
            ScrollView {
                LazyVStack(alignment: .leading, spacing: 8) {
                    ForEach(viewModel.messages, id: \.id) { message in
                        MessageBubble(message: message)
                    }
                }
            }
            .frame(maxHeight: 400)
            // Controls
            HStack(spacing: 16) {
                Button(viewModel.isConnected ? "End" : "Start") {
                    Task {
                        if viewModel.isConnected {
                            await viewModel.endConversation()
                        } else {
                            await viewModel.startConversation()
                        }
                    }
                }
                .buttonStyle(.borderedProminent)
                Button(viewModel.isMuted ? "Unmute" : "Mute") {
                    Task { await viewModel.toggleMute() }
                }
                .buttonStyle(.bordered)
                .disabled(!viewModel.isConnected)
                Button("Send Message") {
                    Task { await viewModel.sendTestMessage() }
                }
                .buttonStyle(.bordered)
                .disabled(!viewModel.isConnected)
            }
            // Agent state indicator
            if viewModel.isConnected {
                HStack {
                    Circle()
                        .fill(viewModel.agentState == .speaking ? .blue : .gray)
                        .frame(width: 10, height: 10)
                    Text(viewModel.agentState == .speaking ? "Agent speaking" : "Agent listening")
                        .font(.caption)
                }
            }
        }
        .padding()
    }
}
struct MessageBubble: View {
    let message: Message
    var body: some View {
        HStack {
            if message.role == .user { Spacer() }
            VStack(alignment: .leading) {
                Text(message.role == .user ? "You" : "Agent")
                    .font(.caption)
                    .foregroundColor(.secondary)
                Text(message.content)
                    .padding()
                    .background(message.role == .user ? Color.blue : Color.gray.opacity(0.3))
                    .foregroundColor(message.role == .user ? .white : .primary)
                    .cornerRadius(12)
            }
            if message.role == .agent { Spacer() }
        }
    }
}
@MainActor
class ConversationViewModel: ObservableObject {
    @Published var messages: [Message] = []
    @Published var isConnected = false
    @Published var isMuted = false
    @Published var agentState: AgentState = .listening
    @Published var connectionStatus = "Disconnected"
    private var conversation: Conversation?
    private var cancellables = Set<AnyCancellable>()
    func startConversation() async {
        do {
            conversation = try await ElevenLabs.startConversation(
                agentId: "your-agent-id",
                config: ConversationConfig()
            )
            setupObservers()
        } catch {
            print("Failed to start conversation: \(error)")
            connectionStatus = "Failed to connect"
        }
    }
    func endConversation() async {
        await conversation?.endConversation()
        conversation = nil
        cancellables.removeAll()
    }
    func toggleMute() async {
        try? await conversation?.toggleMute()
    }
    func sendTestMessage() async {
        try? await conversation?.sendMessage("Hello from the app!")
    }
    private func setupObservers() {
        guard let conversation else { return }
        conversation.$messages
            .assign(to: &$messages)
        conversation.$state
            .map { state in
                switch state {
                case .idle: return "Disconnected"
                case .connecting: return "Connecting..."
                case .active: return "Connected"
                case .ended: return "Ended"
                case .error: return "Error"
                }
            }
            .assign(to: &$connectionStatus)
        conversation.$state
            .map { $0.isActive }
            .assign(to: &$isConnected)
        conversation.$isMuted
            .assign(to: &$isMuted)
        conversation.$agentState
            .assign(to: &$agentState)
    }
}