aiOla Swift SDK

The official Swift SDK for the aiOla API, designed to work seamlessly across iOS, macOS, tvOS, and watchOS platforms.

Documentation

Learn more about the aiOla API and how to use the SDK in our documentation.

Installation

Swift Package Manager

Add the following to your Package.swift file:

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

Or add it through Xcode:

1. File → Add Package Dependencies
2. Enter the repository URL: https://github.com/aiola-api/swift-sdk
3. Select version and add to your target

Usage

Authentication

The aiOla SDK uses a two-step authentication process:

1. Generate Session Token: Use your API key to create a temporary session token, save it for later use
2. Create Client: Use the session token to instantiate the client

Step 1: Generate Session Token

import Aiola

let response = try await AiolaClient.getSessionToken(
    apiKey: "your-api-key"
)

let sessionToken = response.sessionToken
let sessionId = response.sessionID

Step 2: Create Client

let client = try AiolaClient(
    sessionToken: sessionToken
)

Complete Example

import Aiola

func example() async throws {
    do {
        // Step 1: Generate session token
        // Ideally happens in your BFF
        let response = try await AiolaClient.getSessionToken(
            apiKey: "your-api-key"
        )
        
        // Step 2: Create client
        let client = try AiolaClient(
            sessionToken: response.sessionToken
        )
        
        // Step 3: Use client for API calls
        let audioData = try Data(contentsOf: URL(fileURLWithPath: "path/to/your/audio.wav"))
        let transcript = try await client.stt.transcribeFile(
            fileData: audioData,
            fileName: "audio.wav",
            language: "en"
        )
        
        print("Transcript:", transcript.transcript)
        
    } catch {
        print("Error:", error)
    }
}

Session Management

Close Session:

// Terminates the session
let response = try await AiolaClient.closeSession(
    sessionToken: sessionToken
)
print("Session closed at: \(response.deletedAt)")

Custom base URL (enterprises)

let response = try await AiolaClient.getSessionToken(
    apiKey: "your-api-key",
    authBaseURL: "https://mycompany.auth.aiola.ai"
)

let client = try AiolaClient(
    sessionToken: response.sessionToken,
    baseURL: "https://mycompany.api.aiola.ai"
)

Speech-to-Text – transcribe file

import Aiola

func transcribeFile() async throws {
    do {
        // Step 1: Generate session token
        let response = try await AiolaClient.getSessionToken(
            apiKey: "your-api-key"
        )
        
        // Step 2: Create client
        let client = try AiolaClient(
            sessionToken: response.sessionToken
        )
        
        // Step 3: Transcribe file
        let audioData = try Data(contentsOf: URL(fileURLWithPath: "path/to/your/audio.wav"))
        let transcript = try await client.stt.transcribeFile(
            fileData: audioData,
            fileName: "audio.wav",
            language: "en" // supported languages: en, de, fr, es, pr, zh, ja, it
        )
        
        print(transcript.transcript)
    } catch {
        print("Error transcribing file:", error)
    }
}

Speech-to-Text – live streaming

import Aiola

func liveStreaming() async throws {
    do {
        // Step 1: Generate session token, save it
        let response = try await AiolaClient.getSessionToken(
            apiKey: "your-api-key"
        )
        
        // Step 2: Create client using the session token
        let client = try AiolaClient(
            sessionToken: response.sessionToken
        )
        
        // Step 3: Start streaming
        let connection = try await client.stt.stream(
            config: StreamConfig(language: "en")
        )
        
        connection.on(.connect) { _ in
            print("Connected to streaming service")
        }
        
        connection.on(.transcript) { data in
            if let dataArray = data as? [Any],
               let firstItem = dataArray.first,
               let transcriptDict = firstItem as? [String: Any],
               let text = transcriptDict["transcript"] as? String {
                print("Transcript:", text)
            }
        }
        
        connection.on(.disconnect) { _ in
            print("Disconnected from streaming service")
        }
        
        connection.on(.error) { error in
            print("Streaming error:", error)
        }
        
        try await connection.connect()
        
        // Send audio data (example with microphone)
        // You would typically get audio data from AVAudioEngine or similar
        let audioData = Data() // Your audio data here
        connection.send(audioData)
        
    } catch {
        print("Error:", error)
    }
}

Text-to-Speech

import Aiola

func createAudioFile() async throws {
    do {
        let response = try await AiolaClient.getSessionToken(
            apiKey: "your-api-key"
        )
        
        let client = try AiolaClient(
            sessionToken: response.sessionToken
        )
        
        let audioData = try await client.tts.synthesize(
            text: "Hello, how can I help you today?",
            voice: "jess",
            language: "en"
        )
        
        let documentsPath = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
        let audioURL = documentsPath.appendingPathComponent("audio.wav")
        try audioData.write(to: audioURL)
        
        print("Audio file created successfully at:", audioURL.path)
    } catch {
        print("Error creating audio file:", error)
    }
}

Text-to-Speech – streaming

import Aiola

func streamTTS() async throws {
    do {
        let response = try await AiolaClient.getSessionToken(
            apiKey: "your-api-key"
        )
        
        let client = try AiolaClient(
            sessionToken: response.sessionToken
        )
        
        let audioChunks = try await client.tts.stream(
            text: "Hello, how can I help you today?",
            voice: "jess",
            language: "en"
        )
        
        print("Audio chunks received:", audioChunks.count)
    } catch {
        print("Error streaming TTS:", error)
    }
}

iOS Example App

The SDK includes a complete iOS example app that demonstrates real-time microphone streaming:

cd Examples/iOSMicStream
open iOSMicStream.xcodeproj

The example app shows:

• Real-time microphone audio capture
• Live speech-to-text streaming
• Modern SwiftUI interface
• Proper error handling and user feedback

Key Features of the Example:

• Uses AVAudioEngine for microphone capture
• Converts audio to 16-bit PCM (16 kHz, mono)
• Streams audio data through WebSocket
• Displays live transcripts in real-time
• Handles connection states and errors gracefully

Requirements

• iOS: 13.0+
• macOS: 12.0+
• tvOS: 13.0+
• watchOS: 6.0+
• Swift: 5.7+

Dependencies

• Alamofire: HTTP networking and file uploads
• Socket.IO: WebSocket streaming for real-time communication

Running Tests

Unit Tests

swift test

Integration Tests

To run integration tests, you need to set your API key:

1. Open Tests/AiolaIntegrationTests/IntegrationTestConfig.swift
2. Set your API key:

   static let apiKey = "your_actual_api_key_here"

3. Run the integration tests:

   swift test --filter AiolaIntegrationTests

Error Handling

The SDK provides comprehensive error handling with specific error types:

do {
    let transcript = try await client.stt.transcribeFile(
        fileData: audioData,
        fileName: "audio.wav",
        language: "en"
    )
} catch let error as AiolaError {
    switch error {
    case .validationError(let message):
        print("Validation error:", message)
    case .connectionError(let message):
        print("Connection error:", message)
    case .serverError(let message, let code):
        print("Server error (\(code)):", message)
    case .fileError(let message):
        print("File error:", message)
    }
} catch {
    print("Unexpected error:", error)
}

Advanced Configuration

Voice Activity Detection (VAD)

let vadConfig = VadConfig(
    threshold: 0.5,
    minSpeechMs: 250,
    minSilenceMs: 1000,
    maxSegmentMs: 30000
)

let transcript = try await client.stt.transcribeFile(
    fileData: audioData,
    fileName: "audio.wav",
    language: "en",
    vadConfig: vadConfig
)

Keywords

let keywords = [
    "venus": "venuss",
    "aiola": "aiola"
]

let transcript = try await client.stt.transcribeFile(
    fileData: audioData,
    fileName: "audio.wav",
    language: "en",
    keywords: keywords
)

Streaming Configuration

let streamConfig = StreamConfig(
    language: "en",
    keywords: keywords,
    vadConfig: vadConfig,
    timeZone: "UTC"
)

let connection = try await client.stt.stream(config: streamConfig)

License

[Add your license information here]

Support

[Add support/contact information here]