Open-source project
algolia/voice-overlay-ios avatar
algolia/voice-overlay-ios

InstantSearch VoiceOverlay for iOS: speech input with permission handling built in

🗣 An overlay that gets your user’s voice permission and input as text in a customizable UI

556 stars58 forksSwiftMIT

At a glance

What is it?
A Swift overlay that turns a user's voice into text through SFSpeechRecognizer, with customizable screens and a permission flow. It is a UI layer, not a speech engine, and the README leaves some production questions open.
Who is it for?
Adopt InstantSearch VoiceOverlay if you want a ready-made speech input screen with permission handling on iOS and you are willing to accept Apple's SFSpeechRecognizer as the engine. Do not adopt it if you need offline recognition, server-side transcription, or a UI you fully control at the view level.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 145 days ago.
What is it written in?
Mainly Swift, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • algolia/voice-overlay-ios556 ★ · -1
Star history
Repository2026-09-212026-11-15
algolia/voice-overlay-ios557556

-1 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What VoiceOverlay solves, and for whom

Turning speech into text on iOS is not hard. SFSpeechRecognizer does the work. The work around it is what takes time: asking for microphone and speech recognition permissions, showing a screen while the user is still deciding, handling a denial by sending the user to the right pane of Settings, and giving feedback while audio is being captured. InstantSearchVoiceOverlay packages that loop into one controller you present on a view controller.

The README describes the target plainly: it turns the user's voice into text "providing a polished UX while handling for you the necessary permissions." The audience is iOS developers building conversational interfaces, search fields, chatbots, or any input where typing is slower than talking. The repository topics list instant search and conversational UI, which matches the project's origin at Algolia.

If you already have a design system and a custom recording screen, this library is mostly redundant. If you have a text field and a weekend, it saves you the permission edge cases.

How the overlay talks to SFSpeechRecognizer

The controller does not implement recognition itself. The README states it "uses internally the native SFSpeechRecognizer in order to perform the speech to text conversion." That means recognition quality, language coverage, and on-device versus server behavior are Apple's, not this project's.

The abstraction point is the Recordable protocol. The default implementation is a SpeechController initialized with a locale, and the README shows how to substitute your own by passing a speechControllerHandler into the controller's initializer. That is the seam to use if you want to wrap a different engine or a mock in tests.

Results arrive in two ways. You can pass a textHandler and errorHandler to start(on:textHandler:errorHandler:), or conform to VoiceOverlayDelegate and implement recording(text:final:error:). The final flag tells you whether the transcript is still being revised or has settled, which is what you need to decide when to run a search versus when to wait.

Behavioral settings are grouped on the controller's settings property. autoStart defaults to true, meaning the overlay begins recording as soon as it appears. autoStop also defaults to true, and autoStopTimeout defaults to 2 seconds of silence before recording stops. Those defaults are opinionated: a user who pauses to think for two seconds gets cut off unless you raise the timeout.

Adding the package and firing the first overlay

The README offers three installers. CocoaPods is the shortest path for an existing Podfile. Add the pod line, then run pod install.

ruby
pod 'InstantSearchVoiceOverlay', '~> 1.1.0'

For Carthage, add the repository to your Cartfile with the same version range.

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

For Swift Package Manager, the README says to use Xcode 11+ and add the package dependency through File, then Swift Packages, then Add Package Dependency, entering the repository URL. If you are a framework author, the Package.swift dependency looks like this.

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

Before any of that runs, the README requires two Info.plist string keys: Privacy - Microphone Usage Description and Privacy - Speech Recognition Usage Description, each with a human-readable reason. iOS will terminate the app if you present the permission prompt without them.

Then create one controller per view controller and start it from a button action. The README's example prints the transcript and whether it is final.

swift
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))")
        })
    }
}

What you should see: the permission screen on first launch, then the listening screen, then console lines with partial transcripts and a final one. To run the bundled demo instead, clone the repository and run pod install in the demo project before opening it.

Customizing screens without touching the view layer

All visual configuration goes through settings.layout, addressed by screen and constant. The README points to Xcode autocomplete as the discovery mechanism for the available screens and constants, which is honest but means the documentation is the type system rather than a table.

Three examples from the README show the shape: inputScreen.subtitleBulletList takes an array of suggestion strings, inputScreen.titleListening replaces the title shown while recording, and permissionScreen.backgroundColor takes a UIColor. Because these are properties on a settings object, you can set them once at controller creation and forget them.

The result screen is marked Beta in the README. It appears when showResultScreen is set to true, and showResultScreenTimeout defaults to 2, described as the timeout for showing the result screen if no resultScreenText is provided in time. Beta labeling plus a timeout-based fallback is a signal that this path is less settled than the listening flow. Treat it as optional polish, not a foundation.

Where the overlay stops being the right tool

The dependency on SFSpeechRecognizer is the main constraint. Anything Apple's recognizer cannot do, this library cannot do. That includes recognition on platforms outside iOS, since the repository is iOS-only, and any workflow that requires a specific third-party or server-side transcription model for accuracy, language coverage, or data handling reasons.

Permission denial is handled by guiding the user to Settings, which the README illustrates with a screenshot. That is good behavior, but it is still a dead end inside your app: the user must leave, change a setting, and come back. If your product needs to degrade to typing immediately on denial, you are writing that fallback yourself.

The default autoStopTimeout of 2 seconds is a real interaction decision, not a neutral default. Users who dictate slowly or pause mid-sentence will lose the tail of their input. Raising the value changes how long the overlay sits idle.

Finally, the README does not document rollback, analytics hooks, or how the overlay behaves when the app moves to the background mid-recording. Those are questions you will answer by reading Sources/ and Tests/ in the repository rather than the documentation.

Alternatives and how they differ

The closest alternative is not another library but the platform itself: use SFSpeechRecognizer directly and build your own recording UI. You get full control over the permission prompt timing, the visual states, and the transcript handling, at the cost of writing the screens this project already ships. For a team with an existing design system, that is often the cheaper route.

A second option is a cloud transcription API wrapped in your own UI. The difference is architectural: recognition happens off-device, which changes latency, cost, and privacy posture, but also removes the dependence on Apple's on-device and server recognizer behavior. VoiceOverlay's Recordable protocol means you could keep the overlay and swap the engine, but you would be replacing the part the README describes as its core mechanism.

A third path is a commercial voice UI SDK. Those typically bundle wake words, dialog management, and cross-platform clients. VoiceOverlay is deliberately narrower: one screen, one job, MIT-licensed source you can read.

Maintenance, upgrade cost and licence

The repository is not archived, and the last push was on 2026-06-23. The README's badges and examples target Swift 4, and the installation snippets pin the 1.1.0 line with ranges such as ~> 1.1.0 and 1.1.0 ..< 2.0.0. The repository has no published GitHub releases, so the version numbers in the README are the only version signal.

That combination matters for budgeting. A Swift 4 era codebase on a current Xcode toolchain may compile with warnings or require small fixes, and the README does not describe a migration guide or a changelog. Pin the range you install and read the podspec and Package.swift before upgrading across a minor version.

The licence is MIT, stated in the README badge and in LICENSE.md. MIT is permissive: it allows commercial and closed-source use with attribution and the licence text retained. That is a description of the licence terms, not legal advice; if your organization has a policy on bundled dependencies, run it through that process.

Editorial conclusion

Adopt InstantSearch VoiceOverlay if you want a ready-made speech input screen with permission handling on iOS and you are willing to accept Apple's SFSpeechRecognizer as the engine. Do not adopt it if you need offline recognition, server-side transcription, or a UI you fully control at the view level. Before shipping, verify the Info.plist usage descriptions are present, confirm how your app behaves when the user denies microphone or speech recognition access, and check whether the beta result screen fits your flow.

Frequently asked questions

Can I add a VoiceOverlay to my iPhone app?

Yes. The README shows installing InstantSearchVoiceOverlay through CocoaPods, Carthage or Swift Package Manager, adding two Info.plist usage descriptions, and calling start(on:textHandler:errorHandler:) from a button action.

How do I get the voice overlay to appear on iOS?

Create a VoiceOverlayController and call start(on:textHandler:errorHandler:) passing the view controller to present on. On first use the overlay shows the permission screen before the listening screen.

How do I turn off the VoiceOverlay on iOS?

The README does not document a stop or dismiss API. With the default settings the overlay stops recording after autoStopTimeout seconds of silence, which defaults to 2, and it can also be configured to require a tap on the mic by setting autoStop to false.

Can I layer audio recordings with InstantSearchVoiceOverlay?

No. The library converts speech to text through SFSpeechRecognizer and exposes transcripts through a text handler or delegate; the README describes no audio mixing or multi-track recording feature.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/algolia-voice-overlay-ios.svg)](https://hysenlabs.com/projects/algolia-voice-overlay-ios)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/algolia-voice-overlay-ios.svg)](https://hysenlabs.com/projects/algolia-voice-overlay-ios)

Was this useful?