Algolia Voice Overlay for iOS: Adding Voice Input to iOS Apps

What the Library Does and What It Does Not Cover

InstantSearchVoiceOverlay is a Swift library that provides a modal overlay for voice input in iOS apps. When a user taps a voice button, the overlay appears, requests microphone and speech recognition permissions if they have not been granted, records speech, and returns the transcribed text to your code.

The library uses iOS's native `SFSpeechRecognizer` internally for the transcription. It does not connect to any external speech-to-text API or Algolia's search service directly: the voice recognition happens on-device through the system framework. The Algolia connection is intended usage: the library was built so that Algolia's InstantSearch iOS SDK can pass voice queries to an Algolia index, but the voice overlay itself has no hard dependency on Algolia's search infrastructure.

Android is not covered. The repository is iOS-only Swift code. The README also references an Algolia Community forum and Stack Overflow for support, suggesting the library is part of the broader Algolia iOS ecosystem but functions independently.

Setting Up Permissions in Info.plist

Before the overlay can appear, iOS requires two privacy permission entries in your app's `Info.plist`. Without them, the OS will terminate your app when it tries to access the microphone or speech recognizer. The README specifies:

- `Privacy - Microphone Usage Description` with a description such as: `Need the mic for audio to text` - `Privacy - Speech Recognition Usage Description` with a description such as: `Need the speech recognition capabilities for searching tags`

These keys must be present in `Info.plist` before you call `voiceOverlayController.start`. The overlay handles the actual permission prompt dialogs automatically. When permissions are missing or denied, the README states that the overlay guides the user to the correct section of the Settings app rather than silently failing.

Installing the Library: SPM, CocoaPods, and Carthage

The library supports three dependency managers.

For Swift Package Manager, open your project in Xcode 11 or later, navigate to File > Swift Packages > Add Package Dependency, and enter the repository URL. For use in a Swift package, add this to `Package.swift`:

let package = Package(
    // 1.1.0 ..< 2.0.0
    dependencies: [
        .package(url: "https://github.com/algolia/voice-overlay-ios", from: "1.1.0")
    ],
    // ...
)

For CocoaPods, add this line to your Podfile:

pod 'InstantSearchVoiceOverlay', '~> 1.1.0'

For Carthage, add this line to your Cartfile:

github "algolia/voice-overlay-ios" ~> 1.1.0

The Demo project bundled in the repository requires `pod install` before running.

Starting the Overlay and Reading the Text Output

The basic usage pattern creates a `VoiceOverlayController` and calls `start` from a button action:

import InstantSearchVoiceOverlay

class ViewController: UIViewController {

    let voiceOverlayController = VoiceOverlayController()

    @objc func voiceButtonTapped() {

        voiceOverlayController.start(on: self, textHandler: { (text, final) in
            print("voice output: \(String(describing: text))")
            print("voice output: is it final? \(String(describing: final))")
        }, errorHandler: { (error) in
            print("voice output: error \(String(describing: error))")
        })
    }

The `textHandler` closure fires with the transcribed text as the user speaks. The `final` boolean tells you whether the transcription is still in progress or complete. An alternative to the closure is the `VoiceOverlayDelegate` protocol:

func recording(text: String?, final: Bool?, error: Error?) {
    if let error = error {
        print("delegate: error \(error)")
    }

    if error == nil {
        print("delegate: text \(text)")
    }
}

Both patterns receive the same data; the choice is a matter of your app's architecture.

Customization: autoStart, autoStop, and Locale

The `settings` property on `VoiceOverlayController` exposes several options. `autoStart` controls whether recording begins immediately when the overlay appears (default `true`), or waits for the user to tap the microphone button. `autoStop` controls whether recording stops automatically after a period of silence (default `true`), with `autoStopTimeout` setting the silence duration in seconds (default 2).

Locale customization requires a different initialization path. To change the recognition language or use a custom `Recordable` implementation, pass a `speechControllerHandler` closure:

lazy var voiceOverlayController: VoiceOverlayController = {
  let recordableHandler = {
    return SpeechController(locale: Locale(identifier: "en_US"))
  }
  return VoiceOverlayController(speechControllerHandler: recordableHandler)
}()

The README notes that in Swift 4 you can use `Locale.current.languageCode` to read the device's current locale. For a fully custom speech backend, the `Recordable` protocol allows you to substitute your own implementation.

A result screen is available as a beta feature. Setting `showResultScreen` to `true` makes the overlay display the processed result after recording finishes. `showResultScreenTimeout` controls how long the overlay waits for `resultScreenText` to be set before displaying anyway.

Limitations: iOS Only, No Recent Releases, and SFSpeechRecognizer Constraints

The library wraps `SFSpeechRecognizer`, which carries all of that framework's inherent constraints. SFSpeechRecognizer requires an internet connection for most languages on older iOS versions (though newer iOS versions support on-device recognition for some locales). There are also system-level limits on how often speech recognition can be requested in a given time period that the app cannot override.

The repository has no GitHub releases, and the last push was on 2026-06-23. There is no changelog visible in the README, and the version pinned in the installation instructions (1.1.0) has no associated release on GitHub. This means there is no stable release history to reference when auditing which version introduced a specific behavior.

The result screen feature is marked beta in the README, meaning its API may change. Teams relying on it in production should test carefully after any update.

Comparing InstantSearchVoiceOverlay with AVSpeechRecognizer Directly

Using `SFSpeechRecognizer` directly gives you full control over the recognition session, the UI, and the permission flow. The cost is writing and maintaining all of that code yourself: permission dialogs, microphone access, UI state for recording and idle, error handling, and the result screen.

InstantSearchVoiceOverlay provides a finished UI and handles permissions automatically, which covers the most tedious parts. The trade-off is that you are constrained to the visual style and interaction model the overlay provides. If your app needs a voice input experience that is tightly integrated with its own design system, or that needs to run on a surface where a modal overlay is not appropriate, the library's opinionated UI may not fit.

Editorial conclusion

InstantSearchVoiceOverlay is the right choice when you want a ready-made UI layer for voice input on iOS and do not need to build a custom speech recognition interface from scratch. The library handles the permission flow automatically, which is the part most teams find tedious to implement correctly. It is the wrong choice if you need Android support, a cross-platform solution, a custom speech recognition backend beyond SFSpeechRecognizer, or a library with a recent release history: the repository has had no GitHub releases and the last push was on 2026-06-23. Before adopting it, run a compatibility check against your current Xcode and Swift version, since no minimum iOS version or SDK compatibility table is documented in the visible README.

Frequently asked questions

Official sources

1. algolia/voice-overlay-ios on GitHub
2. Issues
3. License: MIT
4. Project website
5. README