Swift - Typecast Documentation

The official Swift library for the Typecast API. Convert text to lifelike speech using AI-powered voices. Compatible with Swift 5.9+ and supports all Apple platforms: iOS, macOS, tvOS, watchOS, and visionOS.

Swift Package

Typecast Swift SDK

Source Code

Typecast Swift SDK Source Code

Requirements

Platform	Minimum Version
iOS	13.0+
macOS	10.15+
tvOS	13.0+
watchOS	6.0+
visionOS	1.0+
Swift	5.9+

Installation

Swift Package Manager
Xcode

Add the following to your Package.swift:

dependencies: [
    .package(url: "https://github.com/neosapience/typecast-sdk.git", from: "0.3.1")
]

Then add Typecast to your target dependencies:

targets: [
    .target(
        name: "YourTarget",
        dependencies: ["Typecast"]
    )
]

Open your project in Xcode
Go to File → Add Package Dependencies…
Enter the repository URL: https://github.com/neosapience/typecast-sdk.git
Select version rules and click Add Package
Select the Typecast library and add it to your target

Latest registered version: typecast-swift/v0.3.1 in the SDK Git tags. Make sure you have Swift 5.9 or higher installed. The SDK uses Swift Concurrency (async/await) which requires this minimum version.

Quick Start

import AVFoundation
import Typecast

let client = TypecastClient(apiKey: "YOUR_API_KEY")
var audioPlayer: AVAudioPlayer?

// Simple usage with convenience method
let audio = try await client.speak(
    "Hello! I'm your friendly text-to-speech assistant.",
    voiceId: "tc_672c5f5ce59fac2a48faeaee"
)

// Play audio directly from data
audioPlayer = try AVAudioPlayer(data: audio.audioData)
audioPlayer?.play()
print("Duration: \(audio.duration)s, Format: \(audio.format.rawValue)")

Features

The Typecast Swift SDK provides powerful features for text-to-speech conversion:

Multiple Voice Models: Support for ssfm-v30 (latest) and ssfm-v21 AI voice models
Multi-language Support: 37 languages including English, Korean, Spanish, Japanese, Chinese, and more
Emotion Control: Preset emotions (normal, happy, sad, angry, whisper, toneup, tonedown) or smart context-aware inference
Audio Customization: Control loudness (LUFS -70 to 0), pitch (-12 to +12 semitones), tempo (0.5x to 2.0x), and format (WAV/MP3)
Voice Discovery: V2 Voices API with filtering by model, gender, age, and use cases
Instant Voice Cloning: Upload a WAV/MP3 sample and create a custom voice ID
Swift Concurrency: Full async/await support for modern Swift development
Thread-Safe: All types conform to Sendable for safe concurrent usage
Timestamp TTS: Word- and character-level alignment data for subtitles, karaoke, and lip-sync
Cross-Platform: Works on iOS, macOS, tvOS, watchOS, and visionOS
Streaming: Real-time chunked audio delivery for low-latency playback

Configuration

Initialize the client with your API key:

import Typecast

// Direct initialization
let client = TypecastClient(apiKey: "your-api-key")

// With custom base URL
let client = TypecastClient(
    apiKey: "your-api-key",
    baseURL: "https://api.typecast.ai"
)

// Using configuration struct
let config = TypecastConfiguration(apiKey: "your-api-key")
let client = TypecastClient(configuration: config)

Advanced Usage

Emotion Control (ssfm-v30)

ssfm-v30 offers two emotion control modes: Preset and Smart.

Smart Mode
Preset Mode
Convenience Method

Let the AI infer emotion from context:

let request = TTSRequest(
    voiceId: "tc_672c5f5ce59fac2a48faeaee",
    text: "Everything is going to be okay.",
    model: .ssfmV30,
    prompt: .smart(SmartPrompt(
        previousText: "I just got the best news!",  // Optional context
        nextText: "I can't wait to celebrate!"      // Optional context
    ))
)

let response = try await client.textToSpeech(request)
audioPlayer = try AVAudioPlayer(data: response.audioData)
audioPlayer?.play()

Explicitly set emotion with preset values:

let request = TTSRequest(
    voiceId: "tc_672c5f5ce59fac2a48faeaee",
    text: "I am so excited to show you these features!",
    model: .ssfmV30,
    prompt: .preset(PresetPrompt(
        emotionPreset: .happy,  // normal, happy, sad, angry, whisper, toneup, tonedown
        emotionIntensity: 1.5   // Range: 0.0 to 2.0
    ))
)

let response = try await client.textToSpeech(request)
audioPlayer = try AVAudioPlayer(data: response.audioData)
audioPlayer?.play()

Use the convenience method for quick emotion control:

let audio = try await client.speak(
    "I'm so excited!",
    voiceId: "tc_672c5f5ce59fac2a48faeaee",
    emotion: .happy,
    intensity: 1.5
)

audioPlayer = try AVAudioPlayer(data: audio.audioData)
audioPlayer?.play()

Audio Customization

Control loudness, pitch, tempo, and output format:

let request = TTSRequest(
    voiceId: "tc_672c5f5ce59fac2a48faeaee",
    text: "Customized audio output!",
    model: .ssfmV30,
    output: OutputSettings(
        targetLufs: -14.0,     // Range: -70 to 0 (LUFS)
        audioPitch: 2,        // Range: -12 to +12 semitones
        audioTempo: 1.2,      // Range: 0.5x to 2.0x
        audioFormat: .mp3     // Options: .wav, .mp3
    ),
    seed: 42  // Unsigned seed for reproducible results
)

let response = try await client.textToSpeech(request)

audioPlayer = try AVAudioPlayer(data: response.audioData)
audioPlayer?.play()
print("Duration: \(response.duration)s, Format: \(response.format.rawValue)")

Voice Discovery (V2 API)

List and filter available voices with enhanced metadata:

// Get all voices
let voices = try await client.getVoices()

// Filter by criteria
let filteredVoices = try await client.getVoices(filter: VoicesV2Filter(
    model: .ssfmV30,
    gender: .female,
    age: .youngAdult
))

// Get a specific voice
let voice = try await client.getVoice(voiceId: "tc_672c5f5ce59fac2a48faeaee")

// Display voice info
print("ID: \(voice.voiceId), Name: \(voice.voiceName)")
print("Gender: \(voice.gender?.rawValue ?? "N/A"), Age: \(voice.age?.rawValue ?? "N/A")")

for model in voice.models {
    print("Model: \(model.version.rawValue), Emotions: \(model.emotions.joined(separator: ", "))")
}

if let useCases = voice.useCases {
    print("Use cases: \(useCases.joined(separator: ", "))")
}

Multilingual Content

The SDK supports 37 languages with automatic language detection:

// Auto-detect language (recommended)
let request = TTSRequest(
    voiceId: "tc_672c5f5ce59fac2a48faeaee",
    text: "こんにちは。お元気ですか。",
    model: .ssfmV30
)

let response = try await client.textToSpeech(request)

// Or specify language explicitly
let koreanRequest = TTSRequest(
    voiceId: "tc_672c5f5ce59fac2a48faeaee",
    text: "안녕하세요. 반갑습니다.",
    model: .ssfmV30,
    language: .korean  // Explicit language code
)

let koreanResponse = try await client.textToSpeech(koreanRequest)

audioPlayer = try AVAudioPlayer(data: koreanResponse.audioData)
audioPlayer?.play()

Streaming

Stream audio chunks in real-time for low-latency playback:

import AVFoundation
import Typecast

let engine = AVAudioEngine()
let playerNode = AVAudioPlayerNode()
let format = AVAudioFormat(commonFormat: .pcmFormatInt16, sampleRate: 32000, channels: 1, interleaved: true)!

engine.attach(playerNode)
engine.connect(playerNode, to: engine.mainMixerNode, format: format)
try engine.start()
playerNode.play()

let stream = try await client.textToSpeechStream(request)
var first = true

for try await chunk in stream {
    var pcmData = chunk
    if first {
        pcmData = chunk.dropFirst(44)  // Skip 44-byte WAV header
        first = false
    }
    let buffer = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: AVAudioFrameCount(pcmData.count / 2))!
    buffer.frameLength = buffer.frameCapacity
    pcmData.withUnsafeBytes { ptr in
        buffer.int16ChannelData!.pointee.update(from: ptr.bindMemory(to: Int16.self).baseAddress!, count: Int(buffer.frameLength))
    }
    playerNode.scheduleBuffer(buffer)
}

WAV streaming format: 32000 Hz, 16-bit, mono PCM. The first chunk includes a 44-byte WAV header (size = 0xFFFFFFFF); subsequent chunks are raw PCM only. For MP3: 320 kbps, 44100 Hz, each chunk is independently decodable. Use Typecast.OutputStream to avoid collision with Foundation.OutputStream.

Timestamp TTS

textToSpeechWithTimestamps() wraps POST /v1/text-to-speech/with-timestamps and returns the audio together with per-word and per-character alignment data — useful for karaoke highlights, subtitle generation, and lip-sync applications.

Basic Usage

import Typecast

let client = TypecastClient(apiKey: "YOUR_API_KEY")

let request = TTSRequestWithTimestamps(
    voiceId: "tc_60e5426de8b95f1d3000d7b5",
    text: "Hello. How are you?",
    model: .ssfmV30
)

let result = try await client.textToSpeechWithTimestamps(request)

audioPlayer = try AVAudioPlayer(data: result.audioData)
audioPlayer?.play()
print("Duration: \(result.audioDuration)s")

for word in result.words {
    print("  [\(word.startTime)s – \(word.endTime)s] \(word.text)")
}

Granularity

Pass granularity: .word (default) or granularity: .char to control the alignment unit.

let request = TTSRequestWithTimestamps(
    voiceId: "tc_60e5426de8b95f1d3000d7b5",
    text: "Hello. How are you?",
    model: .ssfmV30,
    granularity: .char  // required for Japanese / Chinese
)

Subtitle Export

let srt = result.toSrt()
print(srt)

let vtt = result.toVtt()
print(vtt)

Japanese / Chinese: Word-level segmentation is not meaningful for languages without whitespace delimiters (jpn, zho). Use .char granularity for these languages to get character-level alignment.

Instant Voice Cloning

Clone a custom voice from a short audio sample, then pass the returned uc_ voice ID directly to TTS.

import AVFoundation
import Foundation
import Typecast

let client = TypecastClient(apiKey: "YOUR_API_KEY")
var audioPlayer: AVAudioPlayer?
let audioData = try Data(contentsOf: URL(fileURLWithPath: "sample.wav"))

let voice = try await client.cloneVoice(
    audio: audioData,
    filename: "sample.wav",
    name: "My Voice",
    model: "ssfm-v30"
)

let response = try await client.speak(
    "Hello from my cloned voice!",
    voiceId: voice.voiceId
)

audioPlayer = try AVAudioPlayer(data: response.audioData)
audioPlayer?.play()
try await client.deleteVoice(voice.voiceId)

Voice cloning audio must be 25 MB or smaller, the audio duration must be 5-150 seconds, and the custom voice name must be 1-30 characters.

Supported Languages

The SDK supports 37 languages with automatic language detection:

Code	Language	Code	Language	Code	Language
`.english`	English	`.japanese`	Japanese	`.ukrainian`	Ukrainian
`.korean`	Korean	`.greek`	Greek	`.indonesian`	Indonesian
`.spanish`	Spanish	`.tamil`	Tamil	`.danish`	Danish
`.german`	German	`.tagalog`	Tagalog	`.swedish`	Swedish
`.french`	French	`.finnish`	Finnish	`.malay`	Malay
`.italian`	Italian	`.chinese`	Chinese	`.czech`	Czech
`.polish`	Polish	`.slovak`	Slovak	`.portuguese`	Portuguese
`.dutch`	Dutch	`.arabic`	Arabic	`.bulgarian`	Bulgarian
`.russian`	Russian	`.croatian`	Croatian	`.romanian`	Romanian
`.bengali`	Bengali	`.hindi`	Hindi	`.hungarian`	Hungarian
`.minNan`	Hokkien	`.norwegian`	Norwegian	`.punjabi`	Punjabi
`.thai`	Thai	`.turkish`	Turkish	`.vietnamese`	Vietnamese
`.cantonese`	Cantonese

If not specified, the language will be automatically detected from the input text.

Error Handling

The SDK provides a comprehensive TypecastError enum for handling API errors:

import Typecast

do {
    let response = try await client.textToSpeech(request)
} catch let error as TypecastError {
    switch error {
    case .unauthorized(let message):
        // 401: Invalid API key
        print("Invalid API key: \(message)")
    case .paymentRequired(let message):
        // 402: Insufficient credits
        print("Insufficient credits: \(message)")
    case .notFound(let message):
        // 404: Resource not found
        print("Voice not found: \(message)")
    case .validationError(let message):
        // 422: Validation error
        print("Validation error: \(message)")
    case .rateLimitExceeded(let message):
        // 429: Rate limit exceeded
        print("Rate limit exceeded: \(message)")
    case .serverError(let message):
        // 500: Server error
        print("Server error: \(message)")
    case .networkError(let underlyingError):
        // Network connectivity issues
        print("Network error: \(underlyingError.localizedDescription)")
    case .invalidResponse(let message):
        // Invalid response from server
        print("Invalid response: \(message)")
    default:
        print("Error: \(error.localizedDescription)")
    }
    
    // Access status code if available
    if let statusCode = error.statusCode {
        print("HTTP Status: \(statusCode)")
    }
}

Error Types

Error	Status Code	Description
`.badRequest`	400	Invalid request parameters
`.unauthorized`	401	Invalid or missing API key
`.paymentRequired`	402	Insufficient credits
`.notFound`	404	Resource not found
`.validationError`	422	Validation error
`.rateLimitExceeded`	429	Rate limit exceeded
`.serverError`	500	Server error
`.networkError`	-	Network connectivity issues
`.invalidResponse`	-	Invalid response from server

Platform-Specific Usage

iOS

import Typecast
import AVFoundation

class TTSManager {
    private let client = TypecastClient(apiKey: "YOUR_API_KEY")
    private var audioPlayer: AVAudioPlayer?
    
    func speak(_ text: String) async throws {
        let audio = try await client.speak(text, voiceId: "tc_672c5f5ce59fac2a48faeaee")
        
        // Play audio directly from data
        audioPlayer = try AVAudioPlayer(data: audio.audioData)
        audioPlayer?.play()
    }
}

macOS

import Typecast
import AppKit
import AVFoundation

class MacTTSManager {
    private let client = TypecastClient(apiKey: "YOUR_API_KEY")
    private var audioPlayer: AVAudioPlayer?
    
    func speak(_ text: String) async throws {
        let audio = try await client.speak(text, voiceId: "tc_672c5f5ce59fac2a48faeaee")
        
        audioPlayer = try AVAudioPlayer(data: audio.audioData)
        audioPlayer?.play()
    }
    
}

watchOS

import Typecast
import AVFoundation

class WatchTTSManager {
    private let client = TypecastClient(apiKey: "YOUR_API_KEY")
    private var audioPlayer: AVAudioPlayer?
    
    func speak(_ text: String) async throws {
        let audio = try await client.speak(text, voiceId: "tc_672c5f5ce59fac2a48faeaee")
        
        audioPlayer = try AVAudioPlayer(data: audio.audioData)
        audioPlayer?.play()
    }
}

API Reference

TypecastClient Methods

Method	Description
`textToSpeech(_:)`	Convert text to speech audio
`speak(_:voiceId:model:)`	Simple TTS with minimal parameters
`speak(_:voiceId:model:emotion:intensity:)`	TTS with emotion preset
`cloneVoice(audio:filename:name:model:)`	Create a custom voice via instant cloning
`cloneVoice(audioFileURL:name:model:)`	Create a custom voice from a local audio file
`deleteVoice(_:)`	Delete a custom cloned voice
`getVoices(filter:)`	Get available voices with optional filter
`getVoice(voiceId:)`	Get a specific voice by ID

TTSRequest Fields

Field	Type	Required	Description
`voiceId`	`String`	✓	Voice ID (format: `tc_` or `uc_`)
`text`	`String`	✓	Text to synthesize (max 2000 chars)
`model`	`TTSModel`	✓	TTS model (`.ssfmV21` or `.ssfmV30`)
`language`	`LanguageCode`		Language code (auto-detected if omitted)
`prompt`	`TTSPrompt`		Emotion settings (`.basic`, `.preset`, or `.smart`)
`output`	`OutputSettings`		Audio output settings
`seed`	`UInt32`		Unsigned integer seed for reproducibility (≥ 0)

TTSResponse Fields

Field	Type	Description
`audioData`	`Data`	Generated audio data
`duration`	`TimeInterval`	Audio duration in seconds
`format`	`AudioFormat`	Audio format (`.wav` or `.mp3`)

Swift Package

Source Code

​Requirements

​Installation

​Quick Start

​Features

​Configuration

​Advanced Usage

​Emotion Control (ssfm-v30)

​Audio Customization

​Voice Discovery (V2 API)

​Multilingual Content

​Streaming

​Timestamp TTS

​Basic Usage

​Granularity

​Subtitle Export

​Instant Voice Cloning

​Supported Languages

​Error Handling

​Error Types

​Platform-Specific Usage

​iOS

​macOS

​watchOS

​API Reference

​TypecastClient Methods

​TTSRequest Fields

​TTSResponse Fields

Requirements

Installation

Quick Start

Features

Configuration

Advanced Usage

Emotion Control (ssfm-v30)

Audio Customization

Voice Discovery (V2 API)

Multilingual Content

Streaming

Timestamp TTS

Basic Usage

Granularity

Subtitle Export

Instant Voice Cloning

Supported Languages

Error Handling

Error Types

Platform-Specific Usage

iOS

macOS

watchOS

API Reference

TypecastClient Methods

TTSRequest Fields

TTSResponse Fields