### Install via CocoaPods

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Add this line to your Podfile to include SwiftSpeech.

```ruby
pod 'SwiftSpeech'
```

--------------------------------

### Install via Swift Package Manager

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Use this URL in Xcode's Add Packages dialog to add SwiftSpeech to your project.

```html
https://github.com/Cay-Zhang/SwiftSpeech
```

--------------------------------

### Add SwiftSpeech to Podfile with CocoaPods

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Add the SwiftSpeech pod to your Podfile and run pod install to integrate the library.

```ruby
# Podfile
pod 'SwiftSpeech'
```

--------------------------------

### Implement Tap-to-Toggle Recording

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Use `swiftSpeechToggleRecordingOnTap` for a simple tap-to-toggle recording interface. Tapping the button starts recording, and tapping again stops it. This modifier does not support gesture-based cancellation. Requires `SwiftSpeech` and `SwiftUI` imports.

```swift
import SwiftUI
import SwiftSpeech

struct TapToRecordView: View {
    @State private var text = "Tap the button to start"

    var body: some View {
        VStack(spacing: 35) {
            Text(text)
                .font(.system(size: 25, weight: .bold))
                .multilineTextAlignment(.center)
                .padding()

            SwiftSpeech.RecordButton()
                .swiftSpeechToggleRecordingOnTap(
                    sessionConfiguration: SwiftSpeech.Session.Configuration(
                        locale: .current,
                        taskHint: .search,
                        shouldReportPartialResults: true
                    ),
                    animation: .spring(response: 0.3, dampingFraction: 0.5, blendDuration: 0)
                )
                .onRecognizeLatest(update: $text)
        }
        .onAppear {
            SwiftSpeech.requestSpeechRecognitionAuthorization()
        }
    }
}
```

--------------------------------

### On Recognize Latest Modifier

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Binds recognition results directly to a String binding. This is the simplest way to receive recognized text. It automatically ignores results from previous sessions when a new recording starts.

```APIDOC
## POST /api/recognize/latest

### Description
Binds recognition results directly to a String binding. Automatically ignores results from previous sessions when a new recording starts.

### Method
POST

### Endpoint
/api/recognize/latest

### Parameters
#### Query Parameters
- **includePartialResults** (Boolean) - Optional - Whether to include partial recognition results as the user speaks.
- **update** (String binding) - Required - The String binding to update with the recognized text.

### Request Example
```json
{
  "includePartialResults": true,
  "update": "$searchQuery"
}
```

### Response
#### Success Response (200)
- **recognized_text** (String) - The latest recognized text.

#### Response Example
```json
{
  "recognized_text": "This is the recognized text."
}
```
```

--------------------------------

### Tap to Toggle Recording Modifier

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Enables tap-to-toggle recording. Tap once to start recording, tap again to stop. This modifier does not support cancellation via gesture.

```APIDOC
## POST /api/record/toggle

### Description
Enables tap-to-toggle recording. Tap once to start recording, tap again to stop. Does not support cancellation via gesture.

### Method
POST

### Endpoint
/api/record/toggle

### Parameters
#### Query Parameters
- **sessionConfiguration** (SwiftSpeech.Session.Configuration) - Required - Configuration for the speech recognition session.
- **animation** (Animation) - Optional - Animation to be used for the recording gesture.

### Request Example
```json
{
  "sessionConfiguration": {
    "locale": "current",
    "taskHint": "search",
    "shouldReportPartialResults": true
  },
  "animation": ".spring(response: 0.3, dampingFraction: 0.5, blendDuration: 0)"
}
```

### Response
#### Success Response (200)
- **session_id** (String) - The ID of the recording session.

#### Response Example
```json
{
  "session_id": "123e4567-e89b-12d3-a456-426614174000"
}
```
```

--------------------------------

### SwiftSpeech Session Lifecycle Modifiers (Closures)

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Control the recording session lifecycle using SwiftSpeech modifiers. Execute custom actions when recording starts, stops, or is cancelled, with access to the `SwiftSpeech.Session` object.

```swift
.onStartRecording(appendAction: (SwiftSpeech.Session) -> Void)
```

```swift
.onStopRecording(appendAction: (SwiftSpeech.Session) -> Void)
```

```swift
.onCancelRecording(appendAction: (SwiftSpeech.Session) -> Void)
```

--------------------------------

### SwiftSpeech Session Lifecycle Modifiers (Combine Subjects)

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Integrate SwiftSpeech session lifecycle events into a reactive programming flow using Combine Subjects. Modifiers send the `SwiftSpeech.Session` to the specified Subject upon recording start, stop, or cancellation.

```swift
.onStartRecording(sendSessionTo: Subject)
```

```swift
.onStopRecording(sendSessionTo: Subject)
```

```swift
.onCancelRecording(sendSessionTo: Subject)
```

--------------------------------

### Implement Programmatic Speech Recognition with SwiftSpeech.Session

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Demonstrates creating a session with custom configuration, subscribing to text updates via Combine, and managing recording states.

```swift
import SwiftUI
import SwiftSpeech
import Combine

class VoiceRecognitionManager: ObservableObject {
    @Published var recognizedText = ""
    @Published var isRecording = false

    private var session: SwiftSpeech.Session?
    private var cancelBag = Set<AnyCancellable>()

    func startRecording() {
        // Create session with custom configuration
        let config = SwiftSpeech.Session.Configuration(
            locale: Locale(identifier: "en-US"),
            taskHint: .dictation,
            shouldReportPartialResults: true,
            requiresOnDeviceRecognition: false,
            contextualStrings: ["SwiftSpeech", "iOS", "SwiftUI"],
            interactionIdentifier: "main-voice-input",
            audioSessionConfiguration: .recordOnly
        )

        session = SwiftSpeech.Session(configuration: config)

        // Subscribe to string publisher for simple text updates
        session?.stringPublisher?
            .receive(on: DispatchQueue.main)
            .sink(
                receiveCompletion: { [weak self] completion in
                    self?.isRecording = false
                    switch completion {
                    case .finished:
                        print("Recognition completed successfully")
                    case .failure(let error):
                        print("Recognition failed: \(error)")
                    }
                },
                receiveValue: { [weak self] text in
                    self?.recognizedText = text
                }
            )
            .store(in: &cancelBag)

        // Start recording
        session?.startRecording()
        isRecording = true
    }

    func stopRecording() {
        session?.stopRecording()
        isRecording = false
    }

    func cancelRecording() {
        session?.cancel()
        isRecording = false
        recognizedText = ""
    }
}

struct ProgrammaticRecordingView: View {
    @StateObject private var manager = VoiceRecognitionManager()

    var body: some View {
        VStack(spacing: 30) {
            Text(manager.recognizedText)
                .font(.title2)
                .padding()

            HStack(spacing: 20) {
                Button(manager.isRecording ? "Stop" : "Start") {
                    if manager.isRecording {
                        manager.stopRecording()
                    } else {
                        manager.startRecording()
                    }
                }
                .buttonStyle(.borderedProminent)

                Button("Cancel") {
                    manager.cancelRecording()
                }
                .buttonStyle(.bordered)
                .disabled(!manager.isRecording)
            }
        }
        .onAppear {
            SwiftSpeech.requestSpeechRecognitionAuthorization()
        }
    }
}
```

--------------------------------

### SwiftSpeech Demo Views Showcase

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Presents various demo views for SwiftSpeech, including basic recording, color-changing based on voice input, and list building from recordings. These are useful for testing and as reference implementations.

```swift
import SwiftUI
import SwiftSpeech

struct DemoShowcaseView: View {
    var body: some View {
        TabView {
            // Basic demo - simple tap-to-record with text display
            SwiftSpeech.Demos.Basic(localeIdentifier: "en_US")
                .tabItem {
                    Label("Basic", systemImage: "waveform")
                }

            // Colors demo - say a color name to change the UI
            SwiftSpeech.Demos.Colors()
                .tabItem {
                    Label("Colors", systemImage: "paintpalette")
                }

            // List demo - build a list of voice recordings
            SwiftSpeech.Demos.List(localeIdentifier: "en_US")
                .tabItem {
                    Label("List", systemImage: "list.bullet")
                }
        }
    }
}

// Using demos in previews
struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        Group {
            SwiftSpeech.Demos.Basic(locale: .current)
            SwiftSpeech.Demos.Colors()
            SwiftSpeech.Demos.List(locale: Locale(identifier: "zh_Hans_CN"))
        }
    }
}
```

--------------------------------

### Configure Info.plist Usage Descriptions

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Add these keys to your Info.plist to explain why the app requires speech recognition and microphone access.

```xml
<key>NSSpeechRecognitionUsageDescription</key>
<string>This app uses speech recognition to convert your speech into text.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app uses the mircrophone to record audio for speech recognition.</string>
```

--------------------------------

### SwiftSpeech.Demos

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Provides built-in demo views that showcase the library's capabilities, useful for testing or as reference implementations.

```APIDOC
## SwiftSpeech.Demos

### Description
Built-in demo views that showcase the library's capabilities. These can be used for testing or as reference implementations.

### Components
- **SwiftSpeech.Demos.Basic**: Simple tap-to-record interface with text display.
- **SwiftSpeech.Demos.Colors**: Interactive demo where voice input changes UI elements.
- **SwiftSpeech.Demos.List**: Demonstrates building a list of voice recordings.
```

--------------------------------

### SwiftSpeech Session Configuration for Confirmation

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Set up a SwiftSpeech session for yes/no confirmation tasks, using the current locale and disabling partial results to ensure only the final confirmation is captured. Custom vocabulary for confirmation is included. Requires `SwiftSpeech` and `Speech` imports.

```swift
import SwiftSpeech
import Speech

// Configuration for yes/no confirmation
let confirmationConfig = SwiftSpeech.Session.Configuration(
    locale: .current,
    taskHint: .confirmation,
    shouldReportPartialResults: false,  // Only get final result
    contextualStrings: ["yes", "no", "confirm", "cancel"]
)
```

--------------------------------

### Basic SwiftSpeech Session Configuration

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Configure a SwiftSpeech session with a specific locale. Ensure the `SwiftSpeech` and `Speech` frameworks are imported.

```swift
import SwiftSpeech
import Speech

// Basic configuration with locale
let basicConfig = SwiftSpeech.Session.Configuration(
    locale: Locale(identifier: "en_US")
)
```

--------------------------------

### Full SwiftSpeech Session Configuration for Dictation

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Set up a comprehensive configuration for dictation tasks, including locale, task hint, partial result reporting, on-device recognition preference, custom vocabulary, interaction identifier, and audio session settings. Requires `SwiftSpeech` and `Speech` imports.

```swift
import SwiftSpeech
import Speech

// Full configuration for dictation
let dictationConfig = SwiftSpeech.Session.Configuration(
    locale: Locale(identifier: "en_US"),
    taskHint: .dictation,                    // .unspecified, .dictation, .search, .confirmation
    shouldReportPartialResults: true,         // Show text as user speaks
    requiresOnDeviceRecognition: false,       // Use server-based recognition
    contextualStrings: ["SwiftSpeech", "Xcode", "SwiftUI"],  // Custom vocabulary
    interactionIdentifier: "note-taking",     // Analytics identifier
    audioSessionConfiguration: .recordOnly    // .recordOnly, .playAndRecord, .none
)
```

--------------------------------

### Configure Info.plist for Speech Recognition and Microphone Access

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Add required usage description keys to Info.plist for speech recognition and microphone access.

```xml
<!-- Info.plist -->
<key>NSSpeechRecognitionUsageDescription</key>
<string>This app uses speech recognition to convert your speech into text.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone to record audio for speech recognition.</string>
```

--------------------------------

### Preview SwiftSpeech Demos

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Use these views in your SwiftUI preview provider to test built-in speech recognition demos.

```swift
static var previews: some View {
    // Two of the demo views below can take a `localeIdentifier: String` as an argument.
    // Example locale identifiers:
    // 简体中文（中国）= "zh_Hans_CN"
    // English (US) = "en_US"
    // 日本語（日本）= "ja_JP"
    
    Group {
        SwiftSpeech.Demos.Basic(localeIdentifier: yourLocaleString)
        SwiftSpeech.Demos.Colors()
        SwiftSpeech.Demos.List(localeIdentifier: yourLocaleString)
    }
}
```

--------------------------------

### SwiftSpeech Authorization and Basic Usage

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Demonstrates how to request speech recognition authorization and integrate the basic RecordButton with text update functionality.

```APIDOC
## SwiftSpeech.requestSpeechRecognitionAuthorization()

### Description
Requests speech recognition authorization from the user. This must be called before using speech recognition features. The framework handles all authorization state management internally.

### Method
`SwiftSpeech.requestSpeechRecognitionAuthorization()`

### Endpoint
N/A (Client-side function)

### Parameters
None

### Request Example
```swift
import SwiftUI
import SwiftSpeech

struct ContentView: View {
    @State private var text = "Tap to speak"

    var body: some View {
        VStack {
            Text(text)
            SwiftSpeech.RecordButton()
                .swiftSpeechToggleRecordingOnTap()
                .onRecognizeLatest(update: $text)
        }
        .onAppear {
            // Request authorization when the view appears
            SwiftSpeech.requestSpeechRecognitionAuthorization()
        }
    }
}
```

### Response
None (Modifies authorization status)

### Error Handling
Authorization status is managed internally. Errors related to authorization denial or unavailability are handled by the framework.
```

--------------------------------

### Recognize voice with SwiftSpeech.Session

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Initializes a session with a specific locale and contextual strings, then subscribes to the string publisher to handle recognized text.

```swift
let session = SwiftSpeech.Session(configuration: SwiftSpeech.Session.Configuration(locale: Locale(identifier: "en-US"), contextualStrings: ["SwiftSpeech"]))
try session.startRecording()
session.stringPublisher?
    .sink { text in
        // do something with the text
    }
    .store(in: &cancelBag)
```

--------------------------------

### SwiftSpeech Session Configuration with Play-and-Record Audio

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Configure a SwiftSpeech session to use the `playAndRecord` audio session mode, allowing audio playback concurrently with recording. Imports `SwiftSpeech` and `AVFoundation`.

```swift
import SwiftSpeech
import AVFoundation

// Use play-and-record mode - allows audio playback during recording
let playAndRecordConfig = SwiftSpeech.Session.Configuration(
    locale: .current,
    audioSessionConfiguration: .playAndRecord
)
```

--------------------------------

### SwiftUI Integration with Configured Recording View

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Demonstrates how to use a pre-configured SwiftSpeech session within a SwiftUI view using `RecordButton` and `swiftSpeechRecordOnHold`. The `onRecognizeLatest` modifier updates a state variable with the recognized text. Requires `SwiftSpeech` and `SwiftUI` imports.

```swift
import SwiftSpeech
import Speech

// Usage in SwiftUI
struct ConfiguredRecordingView: View {
    @State private var text = ""

    var body: some View {
        SwiftSpeech.RecordButton()
            .swiftSpeechRecordOnHold(
                sessionConfiguration: dictationConfig,
                animation: .spring()
            )
            .onRecognizeLatest(update: $text)
    }
}
```

--------------------------------

### Implement a Transcription List with onRecognize

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Uses onRecognize to update a list of transcriptions by matching session IDs. Requires SwiftSpeech and Speech framework authorization.

```swift
import SwiftUI
import SwiftSpeech
import Speech

struct TranscriptionListView: View {
    @State private var transcriptions: [(id: UUID, text: String, isFinal: Bool)] = []

    var body: some View {
        NavigationView {
            List {
                ForEach(transcriptions, id: \.id) { item in
                    HStack {
                        Text(item.text)
                        Spacer()
                        if item.isFinal {
                            Image(systemName: "checkmark.circle.fill")
                                .foregroundColor(.green)
                        } else {
                            ProgressView()
                        }
                    }
                }
            }
            .navigationTitle("Voice Notes")
            .overlay(
                SwiftSpeech.RecordButton()
                    .swiftSpeechRecordOnHold(
                        locale: .current,
                        distanceToCancel: 100.0
                    )
                    .onStartRecording { session in
                        // Add new empty entry when recording starts
                        transcriptions.append((id: session.id, text: "...", isFinal: false))
                    }
                    .onCancelRecording { session in
                        // Remove entry if recording cancelled
                        transcriptions.removeAll { $0.id == session.id }
                    }
                    .onRecognize(
                        includePartialResults: true,
                        handleResult: { session, result in
                            // Update the correct entry (works across multiple sessions)
                            if let index = transcriptions.firstIndex(where: { $0.id == session.id }) {
                                transcriptions[index].text = result.bestTranscription.formattedString
                                transcriptions[index].isFinal = result.isFinal
                            }
                        },
                        handleError: { session, error in
                            if let index = transcriptions.firstIndex(where: { $0.id == session.id }) {
                                transcriptions[index].text = "Error: \((error as NSError).code)"
                                transcriptions[index].isFinal = true
                            }
                        }
                    )
                    .padding(),
                alignment: .bottom
            )
        }
        .onAppear {
            SwiftSpeech.requestSpeechRecognitionAuthorization()
        }
    }
}
```

--------------------------------

### SwiftSpeech.supportedLocales() Usage

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Demonstrates how to retrieve and display supported locales for speech recognition. Use this to ensure locale support before configuring a session.

```swift
import SwiftUI
import SwiftSpeech

struct LocalePickerView: View {
    @State private var selectedLocale: Locale = .current
    @State private var text = ""

    let supportedLocales = SwiftSpeech.supportedLocales()
        .sorted { $0.identifier < $1.identifier }

    var body: some View {
        VStack(spacing: 20) {
            // Locale picker
            Picker("Language", selection: $selectedLocale) {
                ForEach(supportedLocales, id: ".identifier") {
                    locale in
                    Text(locale.localizedString(forIdentifier: locale.identifier) ?? locale.identifier)
                        .tag(locale)
                }
            }
            .pickerStyle(.menu)

            Text(text)
                .font(.title3)
                .padding()

            SwiftSpeech.RecordButton()
                .swiftSpeechRecordOnHold(
                    sessionConfiguration: SwiftSpeech.Session.Configuration(locale: selectedLocale)
                )
                .onRecognizeLatest(update: $text)
        }
        .onAppear {
            SwiftSpeech.requestSpeechRecognitionAuthorization()

            // Print all supported locales
            print("Supported locales:")
            for locale in SwiftSpeech.supportedLocales() {
                print("  \(locale.identifier)")
            }
        }
    }
}
```

--------------------------------

### Basic SwiftSpeech Integration

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Integrates the SwiftSpeech record button, functional component, and modifiers for speech recognition. Customize session configuration, animation, and cancel distance.

```swift
SwiftSpeech.RecordButton()
    .swiftSpeechRecordOnHold(sessionConfiguration:animation:distanceToCancel:)
    .onRecognizeLatest(update: $text)
```

--------------------------------

### Custom SwiftSpeech Audio Session Configuration

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Define a custom `SwiftSpeech.Session.AudioSessionConfiguration` to manually manage the `AVAudioSession` category, mode, options, and activation/deactivation lifecycle. This requires importing `SwiftSpeech` and `AVFoundation`.

```swift
import SwiftSpeech
import AVFoundation

// Custom audio session configuration
let customAudioConfig = SwiftSpeech.Session.AudioSessionConfiguration(
    onStartRecording: { audioSession in
        try audioSession.setCategory(
            .playAndRecord,
            mode: .voiceChat,
            options: [.defaultToSpeaker, .allowBluetooth]
        )
        try audioSession.setActive(true, options: [])
    },
    onStopRecording: { audioSession in
        try audioSession.setActive(false, options: .notifyOthersOnDeactivation)
    }
)

let configWithCustomAudio = SwiftSpeech.Session.Configuration(
    locale: .current,
    audioSessionConfiguration: customAudioConfig
)
```

--------------------------------

### SwiftSpeech.RecordButton with Hold-to-Record and Cancel Gesture

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Shows how to use the SwiftSpeech.RecordButton with a hold-to-record gesture and a swipe-up-to-cancel functionality, updating recognized text.

```APIDOC
## SwiftSpeech.RecordButton

### Description
A pre-built SwiftUI view component that displays a circular record button with visual feedback. The button automatically changes appearance based on recording state: blue when pending, red when recording, and dark gray when the user intends to cancel.

### Method
`SwiftSpeech.RecordButton()`

### Endpoint
N/A (SwiftUI View Component)

### Parameters
Modifiers like `.swiftSpeechRecordOnHold()` and `.onRecognizeLatest()` are used to configure behavior.

- **`swiftSpeechRecordOnHold(locale:animation:distanceToCancel:)`**: Configures the hold-to-record gesture.
  - `locale` (Locale) - The locale for speech recognition.
  - `animation` (Animation) - The animation for the button's visual state changes.
  - `distanceToCancel` (CGFloat) - The vertical distance the user must swipe up to cancel recording.

- **`onRecognizeLatest(update:)`**: A modifier to receive the latest recognized text.
  - `update` (Binding<String>) - A binding to a String that will be updated with the recognized text.

### Request Example
```swift
import SwiftUI
import SwiftSpeech

struct VoiceInputView: View {
    @State private var recognizedText = ""

    var body: some View {
        VStack(spacing: 30) {
            Text(recognizedText.isEmpty ? "Hold button and speak" : recognizedText)
                .font(.title2)
                .padding()

            // RecordButton with hold-to-record gesture
            // Swipe up 50 points to cancel recording
            SwiftSpeech.RecordButton()
                .swiftSpeechRecordOnHold(
                    locale: Locale(identifier: "en_US"),
                    animation: .spring(response: 0.3, dampingFraction: 0.5, blendDuration: 0),
                    distanceToCancel: 50.0
                )
                .onRecognizeLatest(update: $recognizedText)
        }
        .onAppear {
            SwiftSpeech.requestSpeechRecognitionAuthorization()
        }
    }
}
```

### Response
- **Recognized Text**: Updates the bound String variable provided to `.onRecognizeLatest()`.

### Response Example
(Updates the bound variable, e.g., `$recognizedText`)

### Error Handling
Errors during recording or recognition are handled by the SwiftSpeech framework. Ensure microphone and speech recognition permissions are granted via `Info.plist` and `requestSpeechRecognitionAuthorization()`.
```

--------------------------------

### Initialize FunctionalComponentDelegate

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Delegate used to manually trigger speech recognition logic when implementing custom gestures.

```swift
var delegate = SwiftSpeech.FunctionalComponentDelegate()
```

--------------------------------

### SwiftSpeech Session Configuration for Voice Search

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Configure a SwiftSpeech session for voice search queries using the current locale, enabling partial results and providing specific contextual strings for better accuracy. Imports `SwiftSpeech` and `Speech`.

```swift
import SwiftSpeech
import Speech

// Configuration for voice search
let searchConfig = SwiftSpeech.Session.Configuration(
    locale: .current,
    taskHint: .search,
    shouldReportPartialResults: true,
    contextualStrings: ["product name", "brand name"]
)
```

--------------------------------

### Implement Custom Recording UI with SwiftSpeech.State

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Uses the @Environment(\.swiftSpeechState) property to reactively update view components based on the current recording state.

```swift
import SwiftUI
import SwiftSpeech

struct CustomRecordButton: View {
    // Access the current recording state from the environment
    @Environment(\.swiftSpeechState) var state: SwiftSpeech.State
    @SpeechRecognitionAuthStatus var authStatus

    var backgroundColor: Color {
        switch state {
        case .pending:
            return .blue           // Not recording
        case .recording:
            return .red            // Currently recording
        case .cancelling:
            return .gray           // User intends to cancel (swiping up)
        }
    }

    var iconName: String {
        switch state {
        case .pending, .recording:
            return "mic.fill"
        case .cancelling:
            return "xmark"
        }
    }

    var scale: CGFloat {
        switch state {
        case .pending:
            return 1.0
        case .recording:
            return 1.5
        case .cancelling:
            return 1.2
        }
    }

    var body: some View {
        Circle()
            .fill(backgroundColor)
            .frame(width: 70, height: 70)
            .overlay(
                Image(systemName: iconName)
                    .font(.title)
                    .foregroundColor(.white)
            )
            .scaleEffect(scale)
            .animation(.spring(), value: state)
            .opacity($authStatus ? 1.0 : 0.5)  // Dim if not authorized
    }
}

struct CustomButtonDemoView: View {
    @State private var text = ""

    var body: some View {
        VStack(spacing: 30) {
            Text(text.isEmpty ? "Hold button to speak" : text)

            CustomRecordButton()
                .swiftSpeechRecordOnHold(locale: .current)
                .onRecognizeLatest(update: $text)
        }
        .onAppear {
            SwiftSpeech.requestSpeechRecognitionAuthorization()
        }
    }
}
```

--------------------------------

### SwiftSpeech.supportedLocales()

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Retrieves a set of all locales supported by the speech recognition system to verify compatibility before session configuration.

```APIDOC
## SwiftSpeech.supportedLocales()

### Description
Returns a set of all locales supported by the speech recognition system. Use this to verify locale support before configuring a session.

### Method
Static Function

### Response
- **Set<Locale>** - A collection of supported locales available for speech recognition.
```

--------------------------------

### Implement Hold-to-Record Gesture

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Use `swiftSpeechRecordOnHold` to enable a press-and-hold gesture for recording. Release the button to stop. Swiping up beyond a specified distance cancels the recording. Requires `SwiftSpeech` and `SwiftUI` imports.

```swift
import SwiftUI
import SwiftSpeech
import Speech

struct HoldToRecordView: View {
    @State private var transcript = ""
    @State private var isRecording = false

    var body: some View {
        VStack(spacing: 40) {
            Text(transcript)
                .font(.headline)
                .foregroundColor(isRecording ? .red : .primary)

            SwiftSpeech.RecordButton()
                .swiftSpeechRecordOnHold(
                    sessionConfiguration: SwiftSpeech.Session.Configuration(
                        locale: Locale(identifier: "en_US"),
                        taskHint: .dictation,
                        shouldReportPartialResults: true,
                        contextualStrings: ["SwiftSpeech", "SwiftUI"]
                    ),
                    animation: .interactiveSpring(),
                    distanceToCancel: 100.0
                )
                .onStartRecording { session in
                    isRecording = true
                    print("Started recording session: \(session.id)")
                }
                .onStopRecording { session in
                    isRecording = false
                    print("Stopped recording session: \(session.id)")
                }
                .onCancelRecording { session in
                    isRecording = false
                    transcript = "Recording cancelled"
                    print("Cancelled session: \(session.id)")
                }
                .onRecognizeLatest(
                    includePartialResults: true,
                    handleResult: { session, result in
                        transcript = result.bestTranscription.formattedString
                        if result.isFinal {
                            print("Final result: \(transcript)")
                        }
                    },
                    handleError: { session, error in
                        transcript = "Error: \(error.localizedDescription)"
                    }
                )
        }
        .padding()
        .onAppear {
            SwiftSpeech.requestSpeechRecognitionAuthorization()
        }
    }
}
```

--------------------------------

### Add SwiftSpeech Package to Xcode Project

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Add the SwiftSpeech package to your Xcode project using the provided URL.

```swift
// In Xcode: File → Add Packages → Enter the URL below
// https://github.com/Cay-Zhang/SwiftSpeech
```

```swift
dependencies: [
    .package(url: "https://github.com/Cay-Zhang/SwiftSpeech", from: "0.9.3")
]
```

--------------------------------

### SwiftSpeech Session Configuration with Record-Only Audio

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Configure a SwiftSpeech session to use the `recordOnly` audio session mode, which silences other audio during recording. This requires importing `SwiftSpeech` and `AVFoundation`.

```swift
import SwiftSpeech
import AVFoundation

// Use record-only mode (default) - silences other audio during recording
let recordOnlyConfig = SwiftSpeech.Session.Configuration(
    locale: .current,
    audioSessionConfiguration: .recordOnly
)
```

--------------------------------

### Observe SwiftSpeech state and authorization

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Environment variables used within custom view components to track recording state and speech recognition authorization status.

```swift
@Environment(\.swiftSpeechState) var state: SwiftSpeech.State
@SpeechRecognitionAuthStatus var authStatus
```

--------------------------------

### Request Speech Recognition Authorization

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Call this method to trigger the system authorization prompt, typically within an onAppear modifier.

```swift
.onAppear {
    SwiftSpeech.requestSpeechRecognitionAuthorization()
}
```

--------------------------------

### Define SwiftSpeech.State enum

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Represents the possible states of a recording session, including pending, active recording, and cancellation intent.

```swift
enum SwiftSpeech.State {
    /// Indicating there is no recording in progress.
    /// - Note: It's the default value for `@Environment(\.swiftSpeechState)`.
    case pending
    /// Indicating there is a recording in progress and the user does not intend to cancel it.
    case recording
    /// Indicating there is a recording in progress and the user intends to cancel it.
    case cancelling
}
```

--------------------------------

### SwiftSpeech Session Configuration with No Audio Management

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Configure a SwiftSpeech session to disable automatic audio session management, giving the developer full control over the `AVAudioSession`. Requires `SwiftSpeech` and `AVFoundation` imports.

```swift
import SwiftSpeech
import AVFoundation

// Disable automatic audio session management
let noAudioConfig = SwiftSpeech.Session.Configuration(
    locale: .current,
    audioSessionConfiguration: .none
)
```

--------------------------------

### SwiftSpeech RecordButton with Hold-to-Record Gesture

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Use the RecordButton with a hold-to-record gesture. Swipe up to cancel recording. Configure locale and animation for the gesture.

```swift
import SwiftUI
import SwiftSpeech

struct VoiceInputView: View {
    @State private var recognizedText = ""

    var body: some View {
        VStack(spacing: 30) {
            Text(recognizedText.isEmpty ? "Hold button and speak" : recognizedText)
                .font(.title2)
                .padding()

            // RecordButton with hold-to-record gesture
            // Swipe up 50 points to cancel recording
            SwiftSpeech.RecordButton()
                .swiftSpeechRecordOnHold(
                    locale: Locale(identifier: "en_US"),
                    animation: .spring(response: 0.3, dampingFraction: 0.5, blendDuration: 0),
                    distanceToCancel: 50.0
                )
                .onRecognizeLatest(update: $recognizedText)
        }
        .onAppear {
            SwiftSpeech.requestSpeechRecognitionAuthorization()
        }
    }
}
```

--------------------------------

### Advanced Recognition with onRecognizeLatest

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Use onRecognizeLatest to access the full SFSpeechRecognitionResult object for advanced features. This includes obtaining confidence scores from segments and checking if the recognition is final. Ensure speech recognition authorization is requested before use.

```swift
import SwiftUI
import SwiftSpeech
import Speech

struct AdvancedRecognitionView: View {
    @State private var transcript = ""
    @State private var confidence: Float = 0.0
    @State private var segmentCount = 0
    @State private var errorMessage: String?

    var body: some View {
        VStack(spacing: 20) {
            Text(transcript)
                .font(.title3)

            HStack {
                Text("Confidence: \(String(format: \"%.1f%%\", confidence * 100))")
                Text("Segments: \(segmentCount)")
            }
            .font(.caption)
            .foregroundColor(.secondary)

            if let error = errorMessage {
                Text(error)
                    .foregroundColor(.red)
                    .font(.caption)
            }

            SwiftSpeech.RecordButton()
                .swiftSpeechRecordOnHold(locale: Locale(identifier: "en_US"))
                .onRecognizeLatest(
                    includePartialResults: true,
                    handleResult: { session, result in
                        // Access full SFSpeechRecognitionResult
                        transcript = result.bestTranscription.formattedString
                        segmentCount = result.bestTranscription.segments.count

                        // Get confidence from segments
                        if let lastSegment = result.bestTranscription.segments.last {
                            confidence = lastSegment.confidence
                        }

                        // Check if recognition is complete
                        if result.isFinal {
                            print("Final transcript for session \(session.id): \(transcript)")
                        }
                    },
                    handleError: { session, error in
                        errorMessage = "Recognition failed: \(error.localizedDescription)"
                        print("Error in session \(session.id): \(error)")
                    }
                )
        }
        .padding()
        .onAppear {
            SwiftSpeech.requestSpeechRecognitionAuthorization()
        }
    }
}
```

--------------------------------

### Apply SwiftSpeech recording modifiers

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Functional components that attach recording gestures to views, supporting either hold-to-record or tap-to-toggle interactions.

```swift
// They already support SwiftSpeech Modifiers.
func swiftSpeechRecordOnHold(
    sessionConfiguration: SwiftSpeech.Session.Configuration = SwiftSpeech.Session.Configuration(),
    animation: Animation = SwiftSpeech.defaultAnimation,
    distanceToCancel: CGFloat = 50.0
) -> some View

func swiftSpeechToggleRecordingOnTap(
    sessionConfiguration: SwiftSpeech.Session.Configuration = SwiftSpeech.Session.Configuration(),
    animation: Animation = SwiftSpeech.defaultAnimation
)
```

--------------------------------

### @SpeechRecognitionAuthStatus Property Wrapper

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

A property wrapper that provides reactive access to the speech recognition authorization status. The projected value ($authStatus) returns a Bool indicating whether authorization is granted.

```APIDOC
## @SpeechRecognitionAuthStatus Property Wrapper

A property wrapper that provides reactive access to the speech recognition authorization status. The projected value ($authStatus) returns a Bool indicating whether authorization is granted.

### Authorization Statuses
- **notDetermined**: Authorization not requested yet.
- **denied**: Speech recognition denied.
- **restricted**: Speech recognition restricted.
- **authorized**: Speech recognition authorized.
- **unknown default**: Unknown status.

### Example Usage
```swift
import SwiftUI
import SwiftSpeech
import Speech

struct AuthorizationAwareView: View {
    @SpeechRecognitionAuthStatus var authStatus

    var statusText: String {
        switch authStatus {
        case .notDetermined:
            return "Authorization not requested yet"
        case .denied:
            return "Speech recognition denied"
        case .restricted:
            return "Speech recognition restricted"
        case .authorized:
            return "Speech recognition authorized"
        @unknown default:
            return "Unknown status"
        }
    }

    var body: some View {
        VStack(spacing: 20) {
            Text(statusText)
                .foregroundColor($authStatus ? .green : .red)

            if $authStatus {
                RecordingInterface()
            } else if authStatus == .notDetermined {
                Button("Request Permission") {
                    SwiftSpeech.requestSpeechRecognitionAuthorization()
                }
            } else {
                Button("Open Settings") {
                    if let url = URL(string: UIApplication.openSettingsURLString) {
                        UIApplication.shared.open(url)
                    }
                }
            }
        }
        .onAppear {
            SwiftSpeech.requestSpeechRecognitionAuthorization()
        }
    }
}

struct RecordingInterface: View {
    @State private var text = ""

    var body: some View {
        VStack {
            Text(text)
            SwiftSpeech.RecordButton()
                .swiftSpeechToggleRecordingOnTap()
                .onRecognizeLatest(update: $text)
        }
    }
}
```
```

--------------------------------

### SwiftSpeech.State Enumeration

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

An enumeration representing the current recording state. Used by View Components to update their appearance based on user interaction.

```APIDOC
## SwiftSpeech.State

An enumeration representing the current recording state. Used by View Components to update their appearance based on user interaction.

### States
- **pending**: Not recording.
- **recording**: Currently recording.
- **cancelling**: User intends to cancel (swiping up).

### Example Usage
```swift
import SwiftUI
import SwiftSpeech

struct CustomRecordButton: View {
    @Environment(\.swiftSpeechState) var state: SwiftSpeech.State
    @SpeechRecognitionAuthStatus var authStatus

    var backgroundColor: Color {
        switch state {
        case .pending:
            return .blue
        case .recording:
            return .red
        case .cancelling:
            return .gray
        }
    }

    var iconName: String {
        switch state {
        case .pending, .recording:
            return "mic.fill"
        case .cancelling:
            return "xmark"
        }
    }

    var scale: CGFloat {
        switch state {
        case .pending:
            return 1.0
        case .recording:
            return 1.5
        case .cancelling:
            return 1.2
        }
    }

    var body: some View {
        Circle()
            .fill(backgroundColor)
            .frame(width: 70, height: 70)
            .overlay(
                Image(systemName: iconName)
                    .font(.title)
                    .foregroundColor(.white)
            )
            .scaleEffect(scale)
            .animation(.spring(), value: state)
            .opacity($authStatus ? 1.0 : 0.5)
    }
}
```
```

--------------------------------

### SwiftSpeech On-Device Recognition Configuration

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Configure SwiftSpeech for on-device-only recognition, which is available on iOS 13+ and supports a limited set of languages. This configuration requires `SwiftSpeech` and `Speech` imports.

```swift
import SwiftSpeech
import Speech

// On-device only recognition (iOS 13+, limited languages)
let offlineConfig = SwiftSpeech.Session.Configuration(
    locale: Locale(identifier: "en_US"),
    requiresOnDeviceRecognition: true
)
```

--------------------------------

### Request Speech Recognition Authorization in SwiftUI

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Request speech recognition authorization when the view appears. This must be called before using speech recognition features.

```swift
import SwiftUI
import SwiftSpeech

struct ContentView: View {
    @State private var text = "Tap to speak"

    var body: some View {
        VStack {
            Text(text)
            SwiftSpeech.RecordButton()
                .swiftSpeechToggleRecordingOnTap()
                .onRecognizeLatest(update: $text)
        }
        .onAppear {
            // Request authorization when the view appears
            SwiftSpeech.requestSpeechRecognitionAuthorization()
        }
    }
}
```

--------------------------------

### Manage Speech Recognition Authorization

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Utilizes the @SpeechRecognitionAuthStatus property wrapper to check permissions and conditionally display UI elements.

```swift
import SwiftUI
import SwiftSpeech
import Speech

struct AuthorizationAwareView: View {
    // Access the authorization status
    @SpeechRecognitionAuthStatus var authStatus

    var statusText: String {
        switch authStatus {
        case .notDetermined:
            return "Authorization not requested yet"
        case .denied:
            return "Speech recognition denied"
        case .restricted:
            return "Speech recognition restricted"
        case .authorized:
            return "Speech recognition authorized"
        @unknown default:
            return "Unknown status"
        }
    }

    var body: some View {
        VStack(spacing: 20) {
            Text(statusText)
                .foregroundColor($authStatus ? .green : .red)

            if $authStatus {
                // Show recording interface only when authorized
                RecordingInterface()
            } else if authStatus == .notDetermined {
                Button("Request Permission") {
                    SwiftSpeech.requestSpeechRecognitionAuthorization()
                }
            } else {
                Button("Open Settings") {
                    if let url = URL(string: UIApplication.openSettingsURLString) {
                        UIApplication.shared.open(url)
                    }
                }
            }
        }
        .onAppear {
            SwiftSpeech.requestSpeechRecognitionAuthorization()
        }
    }
}

struct RecordingInterface: View {
    @State private var text = ""

    var body: some View {
        VStack {
            Text(text)
            SwiftSpeech.RecordButton()
                .swiftSpeechToggleRecordingOnTap()
                .onRecognizeLatest(update: $text)
        }
    }
}
```

--------------------------------

### Bind Recognition Results to String

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

The `onRecognizeLatest` modifier binds recognition results directly to a String binding, simplifying the process of receiving recognized text. It automatically handles new sessions and ignores outdated results. Useful for direct text updates in UI elements like TextFields.

```swift
import SwiftUI
import SwiftSpeech

struct SimpleVoiceInputView: View {
    @State private var searchQuery = ""

    var body: some View {
        VStack(spacing: 20) {
            TextField("Search...", text: $searchQuery)
                .textFieldStyle(RoundedBorderTextFieldStyle())
                .padding()

            // Simple binding - recognized text updates $searchQuery automatically
            SwiftSpeech.RecordButton()
                .swiftSpeechToggleRecordingOnTap(locale: .current)
                .onRecognizeLatest(
                    includePartialResults: true,  // Show text as user speaks
                    update: $searchQuery
                )

            Button("Search") {
                print("Searching for: \(searchQuery)")
            }
            .disabled(searchQuery.isEmpty)
        }
        .onAppear {
            SwiftSpeech.requestSpeechRecognitionAuthorization()
        }
    }
}
```

--------------------------------

### SwiftSpeech Recognition Modifiers

Source: https://github.com/cay-zhang/swiftspeech/blob/master/README.md

Handle speech recognition results and errors using SwiftSpeech modifiers. Use `onRecognizeLatest` to ignore previous results or `onRecognize` to subscribe to all results. Customize partial result inclusion and error handling.

```swift
.onRecognizeLatest(
    includePartialResults: Bool = true,
    handleResult: (SwiftSpeech.Session, SFSpeechRecognitionResult) -> Void,
    handleError: (SwiftSpeech.Session, Error) -> Void
)
```

```swift
.onRecognize(
    includePartialResults: Bool = true,
    handleResult: (SwiftSpeech.Session, SFSpeechRecognitionResult) -> Void,
    handleError: (SwiftSpeech.Session, Error) -> Void
)
```

```swift
.onRecognizeLatest(
    includePartialResults: Bool = true,
    update: Binding<String>
)
```

```swift
.printRecognizedText(includePartialResults: Bool = true)
```

--------------------------------

### Hold to Record Modifier

Source: https://context7.com/cay-zhang/swiftspeech/llms.txt

Enables a press-and-hold gesture for recording. The user holds to record and releases to stop. Swiping up beyond a specified distance cancels the recording.

```APIDOC
## POST /api/record/hold

### Description
Enables press-and-hold gesture for recording. Holds to record, releases to stop. Swiping up beyond a specified distance cancels the recording.

### Method
POST

### Endpoint
/api/record/hold

### Parameters
#### Query Parameters
- **sessionConfiguration** (SwiftSpeech.Session.Configuration) - Required - Configuration for the speech recognition session.
- **animation** (Animation) - Optional - Animation to be used for the recording gesture.
- **distanceToCancel** (Double) - Required - The distance in points to swipe up to cancel the recording.

### Request Example
```json
{
  "sessionConfiguration": {
    "locale": "en-US",
    "taskHint": "dictation",
    "shouldReportPartialResults": true,
    "contextualStrings": ["SwiftSpeech", "SwiftUI"]
  },
  "animation": ".interactiveSpring()",
  "distanceToCancel": 100.0
}
```

### Response
#### Success Response (200)
- **session_id** (String) - The ID of the recording session.

#### Response Example
```json
{
  "session_id": "123e4567-e89b-12d3-a456-426614174000"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.